SAP Convergent Charging 3.0 Java/XML API Reference

The SAP CC 3.0 Java/XML API Reference documentation is intended for programmers that need to implement global services provided by SAP Convergent Charging by using some technical interfaces and the Java libraries included in a Software Development Kit (SDK).

See:
Description

Packages

com.highdeal.admin.hci	Provides the administration JAVA / XML APIs.
com.highdeal.calendar.hci	Provides the JAVA / XML APIs related to calendar and specifically to public holidays.
com.highdeal.catalog.hci	Provides API for Price'n Rate cataloging feature.
com.highdeal.changelog.hci	Provides the JAVA / XML APIs related to object change logs and object snapshots.
com.highdeal.chrono.hci	Provides classes for managing chronology.
com.highdeal.cnd.message	Provides Java classes for managing request messages via the Message TCP/IP technical interface of SAP Convergent Charging to provide your landscape with global charging services.
com.highdeal.contract.hci
com.highdeal.currency	Provides classes for currency and money representation.
com.highdeal.filter.hci	Provides some common classes (filters and modification models) for supporting search and bulk modification APIs.
com.highdeal.guiding.common
com.highdeal.hci	Provides support for all JAVA / XML APIs.
com.highdeal.hci.http	Provides classes for calling API through HTTP.
com.highdeal.notification	Provides the Notification Framework.
com.highdeal.pnr.hci	Provides the Price'nRate JAVA / XML APIs.
com.highdeal.pnr.tif	Defines the Transaction Integration Framework (TIF).
com.highdeal.tax.hci	Provides Tax Framework JAVA / XML APIs.
com.highdeal.udr.hci	Provides data models for user defined records.

The SAP CC 3.0 Java/XML API Reference documentation is intended for programmers that need to implement global services provided by SAP Convergent Charging by using some technical interfaces and the Java libraries included in a Software Development Kit (SDK).

This document includes the specifications of the following API sets:

• Java API for Message TCP: Global charging services (event, session, quotation, credit control), notifications ((business and technical alert management)
• Java API for Http Communication Interface (HCI): Master data management (service provider, end customers), administration
• XML API for HCI

Recommendation

Since SAP Convergent Charging 3.0, SAP AG recommends for new implementation projects, to use the technical interface Web Services provided by SAP CC in order to configure the master data and to implement some functional services listed below.

This new technical interface facilitates the integration between SAP CC and another systems (CRM application, provisioning system, billing system, voucher management system). It enables to configure the master data of the new data model (charge plan, provider contract) introduced by SAP CC 3.0.

You can implement the following functions:

• Cross Catalog Management - Complete Configuration of Master Data
• Service Provider Catalog (Pricing Data)
in SAP CC
• Commercial Product Catalog
in an external application
• Provisioning - Complete Configuration of Master Data related to end customers)
• Subscriber Account (Business Partner Management)
• Prepaid and External (Pospaid) Accounts (Business Agreement Management)
• Provider Contract (Contract Management)
• Convergent Charging Services
• Refill Services
• Activation
• Offline Charging Services (Management of Sessions of Batch Rating)

For more information, consult the documentation and the SOAP specifications of the Web Services technical interface (SAP site).

Overview

This overview is an introduction how to program with SAP CC. Some tutorials, examples and use cases are provided. It lists the SAP CC services to implement in your applications and presents the necessary APIs (data model, Java classes...).

Technical Interfaces

SAP Convergent Charging provides you with the following technical interfaces to communicate with the SAP CC Core Server system:

SAP CC Technical Interfaces	Description	SAP CC API Technology	Communication Protocol	External Access Point to the System
Message TCP	Convergent rating and charging messages Notifications	Java API	TCP/IP (High speed interface)	Dispatcher instance (Default port: 2000)
Web Services (WS)	Interface for an integration with a CRM application and a billing system	SOAP API	SOAP/HTTPS, SOAP/HTTP	Updater instance (Default port: 9109)
HTTP Communication Interface (HCI)	Internal interface or for administration	Java API, XML API	XML/HTTPS, XML/HTTP	Updater instance (Default port: 9000) For the initialization of the communication: Dispatcher instance (Default port: 2100)
JCo	This interface is used for the communication of SAP CC with SAP CRM and SAP ERP	N/A	N/A	See the destinations provided by SAP Convergent Charging in the Security Guide

Services of SAP Convergent Charging

According to your needs and to your architecture, SAP Convergent Charging can provide you with several services for your business.

Using the Java API or the XML API, you can implement in your landscape the following key functional services:

SAP CC Functional Services	Stateful Services	Stateless Services	SAP CC Technical Interface	SAP CC API
Catalog Management (Master Data Configuration)	Pricing Catalog Management in SAP CC Pricing Catalog Management for the service provider: Use the SAP CC Core Tool to manually configure this master data in the system. Commercial Product Catalog Management in SAP CC (*) Offer Management Note (*): Since version 3.0, you can implement the management of commercial product catalogs in a CRM application by implementing the Web Services provided by SAP Convergent Charging.	N/A	HCI	Java API, XML API
Provisioning (End Customer Master Data Configuration)	Business Partner and Agreement Management: Subscriber Account Management Contract Management: Subscription Management Technical Data Management: Access Management	N/A	HCI	Java API, XML API
Convergent Rating and Charging Services	Charging, credit control, rating, and quotation Usage event-based: online, offline (*) Charging Blank charging Get estimated price Session-based charging Business notification handling (account and balance alerts) Prerating/postrating (depracated, see session-based charging) Inverse rating (check limit) (depracated) Note (*): The batch rating service is mostly provided by the BART components of SAP Convergent Charging. Consult the SAP CC BART Java/XML API Reference. Activation of periodic or one-off fees Activation of a subscription (for reccuring fees) Bulk activation of subscribtions Note: An enhanced function is also provided by the Web Services technical interface within the Business Job Management process component (see the documentation of this technical interface).	Rating pure Prerating/postrating (deprecated)	Message TCP Asynchronous Synchronous Stateless Notifications	Java API
Administration Services	Shutdown process Monitoring process Configuration process Patch process		HCI	Java API, XML API
	Notification handling (technical alerts)		Message TCP	Java API

Implementation of the Services

During the planning and preparation steps of the implementation phase of your project, you will have to:

• Determine the functional service(s) of SAP CC that you want to implement in your landscape
• Identify the technical interface(s) that is(are) available for this service
• Determine the API set you can implement on your landscape according to your IT policy and other constraints

IMPORTANT NOTE

Before to implement one of these services provided by SAP CC, please consult carefully the Technical Reference Guide for details about the corresponding business processes. All the known limitations are explained to avoid any wrong implementation.

You can use the:

• Java APIs for HCI - message are constructed with Java and exchanged via HTTP or TCP according to the requested service of SAP CC.
• XML APIs for HCI - messages are exchanged via HTTP, your client application has to prepare the request and parse the responses.

API Specification

Main Data Models

Because the data models implement the interface com.highdeal.hci.XMLMarshallable, they defined themselves how to be serialized in or materialized from an XML format.

Master Data Provisioning: First Class Objects

Provisioning: Second Class Objects

Global Rating and Charging

Administration

Conceptual Name	Java API		XML API
	Technical Name	Java Class	Technical Name
Offer	OfferModel	com.highdeal.pnr.hci.OfferModel	offer
Subscription	SubscriptionModel	com.highdeal.pnr.hci.SubscriptionModel	subscription
(User) Access	AccessModel	com.highdeal.pnr.hci.AccessModel	access
(Customized) Charge	ChargeCondition (see OfferModel)	com.highdeal.pnr.hci.ChargeConditionModel
Suboffer	OfferCondition (see OfferModel)	com.highdeal.pnr.hci.OfferConditionModel
(Subscribed) Charge	ChargeActivation (see SubscriptionModel)	com.highdeal.pnr.hci.ChargeActivationModel	chargeActivation
	AccessibleChargeModel (see AccessModel)	com.highdeal.pnr.hci.AccessibleChargeModel	accessibleCharge
Parameter	Parameter (see OfferModel)	com.highdeal.pnr.hci.ParameterModel
Counter Description	CounterDescription (see OfferModel)	com.highdeal.pnr.hci.CounterDescriptionModel
Note: To work with a second class object, it is necessary to use its corresponding first class object that has creation, modification, research and deletion APIs.
n/a	n/a
AdminParameterModel	com.highdeal.admin.hci.AdminParameterModel
InstanceMap	ccom.highdeal.admin.hci.InstanceMap
StatusModel	com.highdeal.admin.hci.StatusModel

Java APIs

Error Handling and Java Exceptions

To take into account the possible errors you need to develop the management of the Java exceptions thrown by the distant SAP CC Core Server system or by the Java libraries of SAP CC. Each exception is precised with a reason message or a reason code for more information.

Technical Interface and Java Package	Communication Errors	Operation Errors
Message TCP	CommunicationFailureException
HCI	CommunicationFailureException BadConfigurationException UnknownTagException	OperationFailureException

The complete list of exceptions that can be thrown is detailed in this documentation.

XML APIs

An XML API is provided by SAP CC to implement the HCI technical interface if you do not want to use the Java API. It is possible to implement some services of SAP CC by using this XML API.

This API is specified with an XML Schema Description (XSD). This documentation includes all the necessary XML fragments of the APIs (both data models and operations). This XSD is also available in the Core SDK of SAP CC as a file (core.xsd) that you can import in your development tools.

Tips: XML Examples

• To have an example in XML about a particular operation, you can set up the SAP CC Core Tool in verbose mode: the tool prints on the system console all the operations sent to the data updating instance and their results in XML.
• To have an example in XML about a particular business object represented by a tree in the Core Tool (ex.: product, charge, charge plan, offer and subscription), use the copy/paste feature.
  For example if you need an XML example of a particular subscription, create the expected subscription in the Core Tool. Then select the subscription node and execute the action "Edit > Copy" (of the menu bar). This action copies the Subscription in XML in the system clipboard. Finally open a simple text editor or an XML editor and execute its paste action.

Error Handling

See the Java APIs.

Warning

Deprecated APIs

Please consult the list of deprecated classes, methods and other items.

Limitations

The known limitations are described in this documentation and in the SAP CC Technical Reference Guide and in all the product documents regarding to the type of users.

Search APIs

The Search APIs are not designed to be used to implement reporting features. They easily can initiate a large amount of data manipulations that can dramatically decrease the performance of the SAP CC Core Server system or can cause system crashes due to memory leak: the memory management is very sensible with Java 1.5.

This Documentation

You can access online to the Javadocs of SAP Convergent Charging in SAP Help Portal at: http://help.sap.com/javadocs/cc.

You can download these Javadocs on SAP Service Marketplace at the following location: https://service.sap.com/instguidescc >> SAP CC 3.0 >> Plan.

Note

This documentation is also available in the following software unit of SAP CC: Software Development Kit (SDK) for the SAP CC Core Server. You can download all the SDKs from SAP Software Download Center (SWDC): Initial version or maintenance versions.

Related Documentation

For more information about the business and technical processes, see the Technical Reference Guide and the Configuration Guide on SAP Service Marketplace at: https://service.sap.com/instguidescc >> SAP CC 3.0 >> Plan:

• SAP CC Technical Reference Guide
• SAP CC Security Guide
• SAP CC Implementation and Configuration Guide

Other Javadocs (for integration with other SAP CC systems)

• SAP CC BART Java/XML API Reference (SAP site)
• SAP CC IEC Java/XML API Reference (SAP site)

Other technical documentation (for integration with other SAP CC systems)

• SAP CC SOAP API Specifications for the Web Services (SAP site)

Other related documents can help you:

• SAP CC System Parameter Reference (SAP site)
• SAP CC Core Tool Online Help
• SAP CC Core Database Structure Reference (SAP site)
• SAP CC Operations Guide

Copyrights and Disclaimer

(c) Copyright 2011 SAP AG. All rights reserved.

This documentation may describe use cases that are not authorized for all customers in all regions. Please refer to your license agreement and comply with any territorial or use restrictions that apply.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

Disclaimer

Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components.

See Also:

AsyncStatefulServiceClient, StatefulServiceClient, StatelessServiceClient, com.highdeal.hci.MessageOperation, SubscriptionModel, OfferModel, SubscriberAccountModel, AccessModel, com.highdeal.admin.hci