This SAP product documentation is intended for programmers that need to implement global business services provided by SAP Convergent Charging 4.1 by using the Java technology or an XML proprietary technology; You design and develop business or technical services that are available on the Message TCP or on the HTTP Communication Interface (HCI) technical interfaces. The necessary Java libraries are included in a Software Development Kit (SAP CC Core SDK).
Caution
Make sure you have the latest version of this documentation extracted from the SDK of SAP Convergent Charging.
Target Audience
- Development consultant
- Technology consultant
- Implementation project team
- Support specialist (level 3)
Overview
This SAP product document includes the functional and technical specifications of the following API sets:
| API Set | Description | Services |
|---|---|---|
| Java API for Message TCP |
The necessary Java packages to implement services provided by the
Message TCP technical interface of SAP CC
|
Global convergent charging services (event, session, quotation, credit control), notifications (business and technical alert management) |
| Java API for HTTP Communication Interface (HCI) |
The necessary Java packages to implement services provided by the
HTTP Communication Interface (HCI) technical interface of SAP CC
|
Master data management (pricing catalogs for service providers, end customer data), administration |
| Java API for allowance data |
A Java package to manipulate the allowances in customer master data
|
|
| XML API for HCI | The necessary XML API to implement services provided by the HTTP Communication Interface (HCI) technical interface of SAP CC | See the business and technical services of HCI |
This 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...).
Recommendation
Since version 3.0, SAP SE recommends for new implementation projects, that you 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 other 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
- Pricing catalog of the service provider stored in SAP CC
- Commercial product catalog in an external application
- Customer Data Provisioning - Complete Configuration of Master Data Related to End Customers)
- Subscriber account, subscriber mapping and range tables (Business Partner Management)
- Prepaid and external (postpaid) accounts (Business Agreement Management)
- Provider contract (Order Capture and Contract Management)
- Convergent Charging Services
- Refill services
- Activation of periodic fees for billing processes synchronization
- Offline charging services (Management of batch rating)
For more information, consult the Web Services Documentation and its SOAP API specifications.
Services of SAP Convergent Charging
Business Services
|
|
|||||||||||||||||||||
|
|
|
|
|
||||||||||||||||||
According to your business requirements and the architecture of your system landscape, SAP Convergent Charging can provide you with several services for your business:
- Master data management (master data provisioning, pricing catalog management)
- Convergent charging
Using the Java API or the XML API, you can implement in your landscape the following key functional services:
| SAP CC Business Services | Stateful Services | Stateless Services | SAP CC Technical Interface | SAP CC API |
|---|---|---|---|---|
Catalog Management (Master Data Configuration) |
Pricing Catalog Management in SAP CC
Commercial Product Catalog Management in SAP CC (*)
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 (Customer Master Data Configuration) |
You cannot manage the new data model based on provider contracts with these Java APIs or XML APIs. See the previous recommendation. Business Partner and Agreement Management
Order Capture and Contract Management
Technical Data Management
|
N/A | HCI | Java API, XML API |
Convergent Rating and Charging Services |
Charging, credit control, rating, and quotation
Note (*) The batch charging service is mostly provided by the BART components of SAP Convergent Charging. Consult the SAP CC BART Java/XML API Reference. |
|
Message TCP | Java API |
Activation of periodic or one-off fees (or reset of the pricing logic)To prepare the invocing and billing processing:
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). |
N/A | Message TCP | Java API | |
| N/A | HCI | Java API, XML API |
Technical Services
| SAP CC Technical Services | Stateful Services | Stateless Services | SAP CC Technical Interface | SAP CC API |
|---|---|---|---|---|
System Administration Services |
|
HCI operations | Java API, XML API | |
Monitoring Services |
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 SAP system 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
- Develop your application
Important Note
Before implementing one of these functional service(s) provided by SAP Convergent Charging (SAP CC), consult carefully the SAP CC Aplication Help for details about the corresponding business processes.
- All the known limitations are explained to avoid any wrong implementation.
- Check all the prerequisites.
- Take into account all the constraints that are relevant for your business. Size your landscape according to your business requirements and rules provided for SAP CC.
- Java APIs for Message TCP - Operation request messages are constructed with Java and exchanged via TCP/IP according to the requested service of SAP CC.
- Java APIs for HCI - Operation request messages are constructed with Java and exchanged via HTTP(s) according to the requested service of SAP CC.
- XML APIs for HCI - Operation request messages are exchanged via HTTP(s), your client application has to prepare the request and parse the responses.
API Specification
Main Data Models
Both the Java APIs and the XML APIs allows you to manage the master data relevant for global charging services that are based on subscriptions. This includes master data related to the pricing catalog, to the commercial product, or to customer master data that includes pricing information:
-
Product Modeling
You can configure commercial offers from a service provider by combining charges or suboffers configured in the pricing catalog owned by this service provider. SAP SE recommends that you manually configure this master data with the SAP CC Core Tool user interface. -
Business Partner and Agreement Management
You can configure the subscriber accounts that relate to end customers' accounts and pricing information. A subscriber account dedicated for subscriptions may include prepaid accounts, external (postpaid) accounts, and credit limit balances. -
Order Capture and Contract Management
You can configure the subscriptions of end customers from a service provider and specify the allowed service consumers by setting up the relevant accesses.
Note
The data models detailed in this documentation include information that is only relevant in the server side (i.e. in the distant and connected SAP CC system). Some methods are not accessible.
Caution
Do not implement these Java/XML APIs to trigger modification operations with master data based on provider contracts and charge plans and initially created with operations available from the Web Services technical interface.
Because the data models implement the
com.highdeal.hci.XMLMarshallable Java interface, they defined themselves
how to be serialized in or materialized from an XML format.
| Master Data Management: First-Class Objects | |||
|---|---|---|---|
| Conceptual Name | Java API | XML API | |
| Technical Name | Java Class | Technical Name | |
| Offer | OfferModel
| com.highdeal.pnr.hci.OfferModel | offer |
| Subscriber Account (Business Partner and Agreement Management) | SubscriberAccountModel
| com.highdeal.pnr.hci.SubscriberAccountModel | subscriberAccount |
| Subscription (Order Capture and Contract Management) | SubscriptionModel
| com.highdeal.pnr.hci.SubscriptionModel | subscription |
| Access | AccessModel
| com.highdeal.pnr.hci.AccessModel | access |
| Master Data: Second-Class Objects | |||
| (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. |
|||
Other Data Models
Consider the data models of theJava packages:
Java APIs
Error Handling and Java Exceptions
To take into account the possible errors you need to design and develop the handling of the Java exceptions thrown
by the connected SAP CC Core Server system or by the SAP CC Java libraries (jar files) that are implemented in your customizedd
client application.
You implement:
- the logging (in your client application) of an exception; the system administrator of this customized application can monitor these recorded log entries and decide to schedule an action plan to resolve a potential anomaly
- some automated treatments of certain exceptions
Each thrown exception includes several reason codes that explain an issue. For each reason, several subcauses are possible. A reason message precises the information relevant for the troubleshooting of each use case. This documentation specifies some troubleshooting operations to identify the correction actions to be performed.
| Technical Interface and Java Package | Exceptions | |||
|---|---|---|---|---|
| Message TCP |
Business failures:
|
|||
| HCI (HTTP Communication Interface) |
The complete list of exceptions that can be
thrown
is detailed in this SAP product documentation: Refer to the specified Java subclasses of
the java.lang.Exception.
In case of unsupported failure, contact your SAP Support Team.
Recommendation
In a production system landscape, please contact a support specialist from your SAP Support Team and report an incident.
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 that you can import in your development tools.
Tips: XML Examples
- To view an XML example about a particular operation,
you can set up the SAP CC Core Tool user interface in
verbosemode: The graphical user interface prints on the system console all the operations sent to the SAP CC system and their results in XML. - To view an XML example about a particular business
object represented by a tree in the SAP CC Core
Tool user interface (charge, charge plan, offer and
subscription), use the copy/paste feature of the graphical user interface.
For example, if you need an XML example of a particular subscription, create the expected subscription in 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 for more information.
Warning
Deprecated APIs
Consult the list of deprecated classes, methods and other items.
Limitations
The known limitations are described in this documentation, in the SAP CC Aplication Help, and in all the SAP 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.
Security
Consult the SAP CC Security Guide documentation to get information on communication security and user rights to perform the service operations described in this documentation. Consult the SAP CC Configuration Guide documentation to set up the technical settings of the SAP CC system related to the management of secured communications and secured user policy.
Configuration
Consult the SAP CC Configuration Guide documentation and the user interfaces to set up the business or technical settings of the SAP CC system: communication settings, business data, master data.
Technical Interfaces
SAP Convergent Charging (SAP CC) provides you with the following technical interfaces to communicate with the SAP CC Core Server system:
| Technical Interface of SAP CC | Description | SAP CC API Technology | Technology and Communication Protocol | Public Access Point to the SAP CC System |
|---|---|---|---|---|
| Message TCP | Java API | Packets over TCP (high speed interface) | Each dispatcher instance of the SAP CC system (Default dedicated port: 2000) | |
| Web Services (WS) | Interface for integration with a CRM application and a billing system | SOAP API | SOAP over HTTPS, SOAP over HTTP |
|
| HTTP Communication Interface (HCI) | Internal interface or for administration | Java API, XML API | XML over HTTPS, XML over HTTP |
|
| JDBC | Interface for the communications with the back-end database systems connected to the SAP CC systems | N/A | JDBC | Each instance of the SAP CC system |
| RFC/JCo | Interface for the communications of SAP CC with SAP CRM and SAP ERP/FI-CA in an integrated SAP Solution scenario | N/A | N/A | See the destinations provided by SAP Convergent Charging in the SAP CC Security Guide documentation |
| Files | Interface for the charging output data in files of SAP CC with SAP CRM and SAP ERP/FI-CA | N/A | N/A | See the repository dedicated to the charging output data generated by the SAP CC Core Server system and its rater instances |
Notes
- Consult the SAP CC Aplication Help documentation for more information about these technical interfaces provided or extended by SAP CC: Web Services, RFC/JCo.
- Consult the SAP CC Configuration Guide documentation for more information about the communication settings and access points available in your SAP CC systems.
This Documentation
The SAP CC Core API Reference (Java and XML) documentation specifies the Java APIs of SAP Convergent Charging 4.1.
You can access online to the Java API References of SAP Convergent Charging in SAP Help Portal at: http://help.sap.com/cc >> SAP CC 4.1 >> Development Information.
You can directly download these Java API References in SAP Help Portal for offline consultation.
Recommendation
Use always the more up-to-date version of this documentation. It is 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
Before developing, refer to the SAP CC Implementation and Configuration Guide for more information about the Customizing activities. Your development relates to a step of the implementation project.
Refer to the SAP CC Security Guide for more information about the technical interfaces and about the implementation of secure communications and services.
Refer to the SAP CC Aplication Help for more information about the business services and processes.
Development Information
The development information includes the following documents:
Other API Specifications
Other Java API References (for integration with other SAP CC systems):
- SAP CC Java/XML API Reference (BART Library) (SAP site)
- SAP CC Java API Reference (IEC Library) (SAP site)
Other technical documentation (for integration with another technical interface):
- SAP CC Web Services Documentation (SAP site) about the SOAP API specifications for this technical interface
Configuration Information
SAP CC System
- SAP CC System Parameter Reference (SAP site)
- SAP CC User Interfaces and Admin+ Primary Help (SAP site) to configure the SAP CC systems and the business data
Master Data and Business Data
- SAP CC Core Tool Primary Help (SAP site) to configure the master data with the SAP CC Core Tool user interface
Additional Documentation
Other related documents can help you:
Copyrights and Disclaimer
(c) Copyright 2016 SAP SE or an SAP affiliate company. All rights reserved.
No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE 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 SE 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
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.
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.
