Java/XML API Reference (Core Library)

This SAP product documentation is intended for programmers that need to implement global business services provided by SAP Convergent Charging 2023 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

Convergent Charging					Master Data Management
Online Charging Session-Based Multiservice Quota reservations and consumption confirmations (partial or complete) Event-Based Immediate Charging (for Direct Debiting) Best-Effort Charging Advice of Charge Stateless Rating		Offline Charging Event-Based Batch Charging Single Charging Advice of Charge Batch Acquisition		Catalog Management Pricing Catalog Commercial Product Catalog		Business Data Taxes, Public Holidays		Customer Master Data Business Partner and Agreement Management Subscriber Account Order Capture and Contract Management Subscription Technical Data Management Access

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 Pricing Catalog Management for the service provider: Use the SAP CC Core Tool user interface to configure manually this master data in the system. Commercial Product Catalog Management in SAP CC (*) Offer Management Note (*) Since main release 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 Subscriber Account Management Order Capture and 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 Advice of charge Session-based charging Business notification handling (account and balance alerts) Prerating/postrating (deprecated, see session-based charging) Inverse rating (check limit) (deprecated) 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.	Rating pure Prerating/postrating (Deprecated)	Message TCP Asynchronous Synchronous Stateless Notifications	Java API
	Activation of periodic or one-off fees (or reset of the pricing logic) To prepare the invoicing and billing processing: Activation of all subscriptions belonging to a subscriber account Bulk activation (*) of all subscriptions or provider contracts stored in the system 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 Asynchronous Synchronous	Java API
		N/A	HCI Activate subscriptions in bulk Activate contracts in bulk	Java API, XML API

Technical Services

SAP CC Technical Services	Stateful Services	Stateless Services	SAP CC Technical Interface	SAP CC API
System Administration Services	System Shutdown System Monitoring System Configuration		HCI operations	Java API, XML API
Monitoring Services	Notification handling (technical alerts for monitoring)		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 Application Help documentation 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.

You can use the:

• 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 the Java packages:

• Notifications (business and technical alert management)
• Administration

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

• Exception and error handling in your message sender

Technical Interface and Java Package	Exceptions
Message TCP Exception and error handling in your charging client	CommunicationFailureException (failure in the SAP CC libraries plugged in your client application) ServerFailureException Business failures: InvalidItemException ForbiddenChargeException TransactionClearingException Online Charging Services SessionOperationException (Online Charging Services) StatelessRateException (Online Charging Services) Offline Charging Services BatchChargeException AcquisitionException RerateSubscriptionException
HCI (HTTP Communication Interface)	CommunicationFailureException BadMessageFormatException BadConfigurationException UnknownTagException ServerFailureException ServerErrorException OperationFailureException and subexceptions OperationFailureErrorException and subexceptions

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 verbose mode: 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 Application Help documentation, 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	Convergent charging (real-time/batch mode) requests Business notifications and alerts	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	For provisioning Web services: Updater instance (Default port: 9080) For charging and recharging Web services: Dispatcher instance (Default dedicated port: 9180) Check the public endpoints available for each process component of the WS technical interface.
HTTP Communication Interface (HCI)	Internal interface or for administration	Java API, XML API	XML over HTTPS, XML over HTTP	For pricing catalog and provisioning operations: Updater instance (Default port: 9000) For the initialization of the communication and administration operations: Dispatcher instance (Default port: 9100)
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 Application 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 2023.

You can access online to the Java API References of SAP Convergent Charging 2023 on SAP Help Portal at: https://help.sap.com/cc >> SAP CC 2023 >> Development Information.

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.

• SAP CC Configuration and Tuning Guide

Refer to the SAP CC Security Guide for more information about the technical interfaces and about the implementation of secure communications and services.

• SAP CC Security Guide

Refer to the SAP CC Application Help for more information about the business services and processes.

• SAP CC Application Help

Development Information

The development information includes the following documents:

• SAP CC Notification Reference
• SAP CC Error Code Reference

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 Cockpit Primary Help to configure some SAP CC system parameters
• SAP CC Admin+ Primary Help (SAP site) to configure the SAP CC Core Server systems (and some business data)
• SAP CC Core Tool Primary Help to configure the necessary SAP CC users in your SAP system landscape
• Other SAP CC User Interfaces (SAP site) to configure the SAP CC systems (and some business data)

Master Data and Business Data

To configure some master data and business data manually, refer to the primary help of the following SAP CC user interfaces:

• Cockpit (some elements in the pricing catalogs such as mapping table classes and mapping tables)
• Core Tool (all elements in the pricing catalogs for the service to monetize, all elements in customer master data)
• Setup Tool (VAT rates and rules for example)

Additional Documentation

Other documents can help you:

• SAP CC Database References (SAP site)
• SAP CC Administration Guide
• SAP CC Installation and Maintenance Guide

Copyrights and Disclaimer

(c) Copyright 2023 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.

Packages

Package	Description
com.highdeal.admin.hci	This Java package provides you with the classes for implementing the Administration Services from the HCI technical interface of SAP CC; With this package you can develop a client application able to manage the activation process, the cleanup process, system parameters, authorizations and roles for SAP CC users, troubleshooting operations.
com.highdeal.allowance.tool	This Java package provides you with Java classes and methods that allows you to manipulate allowance data in your Java-based application.
com.highdeal.barbus	This Java package is deprecated.
com.highdeal.batchgroup	This Java package provides the necessary Java class for developing with batch rating groups; You use this package when implementing a customized assignment policy of batch rating groups in contracts with the com.highdeal.batchgroup.contract package.
com.highdeal.batchgroup.contract	This Java package provides a Java interface for implementing a customized assignment policy of batch rating groups in contracts when your system landscape provides offline charging services; With this package you can develop a Java class that implements the IContractBatchRatingGroupAssignmentPolicy interface.
com.highdeal.calendar.hci	This Java package provides you with the necessary Java classes for handling calendars and public holidays; This business data is stored in SAP CC to design and set up the pricing logic based on public holidays.
com.highdeal.catalog.hci	This Java package provides you with the classes for implementing the management of pricing catalogs for a service provider; Basically this master data is manually configured by using the SAP CC Core Tool user interface.
com.highdeal.chrono.hci	This Java package provides you with the necessary Java classes for handling a chronology of period objects; A lot of data models include a chronology of their configuration.
com.highdeal.cnd.message	This Java package provides the main Java classes and interfaces to implement the Message TCP high-speed technical interface of SAP CC; With this package, you can develop a client application able to send chargeable items to the SAP CC system to charge (online or offline) or quote for the usage of a customer service by end customers.
com.highdeal.contract.hci	This Java package provides you with a search filter specialized for working with charging contracts in customer master data of the service provider; A charging contract is the charging view of a provider contract.
com.highdeal.currency	This Java package provides you with all the Java classes necessary for managing currency and money in your client application.
com.highdeal.error	This Java package extends the Java exception concept with error handling functions; two Java interfaces define the necessary methods.
com.highdeal.filter.hci	This Java package provides you with all the generic Java classes and Java interfaces necessary for dealing with search operations and bulk modification operations; These classes (SearchFilterModel, ModificationModel) are extended in the relevant operation requests.
com.highdeal.guiding
com.highdeal.guiding.common	This Java package provides you with all the generic classes necessary for dealing with guiding.
com.highdeal.hci	This Java package provides the main Java classes and Java interfaces to implement the management of the communications between your client application and the connected SAP CC system via the HTTP Communication Interface (HCI) technical interface of SAP Convergent Charging; With this package, you can develop a client application able to send multiple operation requests and handle the results and exceptions.
com.highdeal.hci.http	This Java package provides you with the Java classes for implementing the calling API through the HTTP protocol in HCI; You use the HttpMessageSenderFactory class.
com.highdeal.mappingtable.hci	This Java package provides you with all the necessary Java classes for managing mapping table classes, mapping tables, and subscriber mapping tables in the master data of a service provider; These business data tables extend your data configuration features to highly customize the master data dedicated to the rating (dynamic pricing) and charging of customer services.
com.highdeal.notification	This Java package provides you with all the Java classes necessary to develop a client application that implements the handling of notification services in your SAP CC system landscape; This service is provided by the Message TCP technical interface and benefits from its features (high availability, ...).
com.highdeal.pnr.hci	This Java package provides you with all the necessary Java classes for managing the master data of a service provider: elements of the pricing catalogs, master data related to the end customers who consume the marketable service; This master data allows you to configure the pricing and charging of customer services.
com.highdeal.pnr.tif	This Java package provides you with the Java interfaces that define the Transaction Integration Framework (TIF).
com.highdeal.rangetable.common	This Java package provides you with all the generic classes necessary for dealing with range tables.
com.highdeal.rangetable.hci	This Java package provides you with all the necessary Java classes for managing range table classes, range tables, and subscriber range tables in the master data of a service provider; These business data tables extend your data configuration features to highly customize the master data dedicated to the rating (dynamic pricing) and charging of customer services.
com.highdeal.tax	This Java package defines the tax statuses that can be set in the charged transactions generated by the SAP CC Core Server system.
com.highdeal.tax.hci	This Java package provides you with all the Java classes necessary to develop a client application that can configure taxation data in the master data managed in SAP Convergent Charging; Some maintenance operations can also be implemented.
com.highdeal.udr.hci	This Java package defines the AttributeDescriptionModel Java class that represents the description of an attribute as seen by your client application; You use attribute descriptions when implementing some search filters in your search operations.