Web Services Documentation

This SAP product documentation specifies the SOAP APIs for the Web Services technical interface provided by SAP Convergent Charging 4.1. The Web Services (WS) deliver a set of services (see process components) dedicated to the new master data model based on provider contracts (see charging contracts). This technical interface is available from the SAP CC Core Server system and accessible endpoints. Your client application or system must consume these business services.

• These Web Services enable the management of master data and product modeling stored in SAP CC or in an external system, the provisioning of customer master data (subscriber accounts with prepaid accounts, provider contracts (charging view)).
• These Web Services provide some business services that you can implement in your SAP system landscape: the offline charging of customers' consumptions, the refilling of prepaid accounts. Some service operations are available to activate the recurring charges of the contracts. These service operations are used by an external scheduler, which triggers the periodic fees (recurring charges) of the contracts (and subscriptions) to update the charging data stored in SAP CC.

Target Audience

• Technology consultant
• Development consultant
• Project implementation team

Definition

SAP CC Web Services deliver a set of services related to the charging and the refilling processes. These operations enable the charging of customers' consumptions and the refilling of prepaid accounts.

SAP Convergent Charging also provides some business services to activate the recurring charges of the contracts. Normally, this service is consumed by an external scheduler, which triggers the recurring charges of the contracts.

See the SAP CC Security Guide to get information on user authorizations and rights to perform the service operations described in this documentation.

Business Context and Use

SAP CC Web Services are a technical interface dedicated to the integration of SAP CC with a CRM application such as SAP CRM or with a billing system such as SAP ERP. Use this technical interface if you want to manage master data stored in SAP Convergent Charging or if you want to perform operations such as charging and refilling from a CRM.

A prerequisite for the integration is to define the pricing logic and the charging and refilling rules in SAP Convergent Charging.

The standard integration of SAP Convergent Charging with a CRM can be split into three stages:

• The definition of the commercial product and its catalog: In the CRM application, you combine the charge plans and the refill plans defined in SAP Convergent Charging (see charge plan class and refill plan class) to set up your commercial product and its catalog of marketable services. Optionally, you can customize the pricing information configured in SAP CC by enriching and maintaining some master data related in a pricing catalog owned by the service provider (see mapping tables or range tables for tiered pricing)
• The customer data provisioning in SAP Convergent Charging from the CRM with their accounts, which can be prepaid or external. Notice that external accounts are links to the postpaid accounts managed by the invoicing system.
• The provisioning of pricing and charging information in contracts stored in SAP Convergent Charging from the CRM.

Provided Services

For implementing some business services in your system landscape, SAP CC Web Services provide you with process components categorized as follows:

• Management of master data
• Business processing
• Restricted services

Management of Master Data

The master data includes pricing and charging configuration settings that are necessary to rate and charge the use of customer services. The service provider is the owner of the master data.

Management of Master Data for Product Modeling

• Catalog Management

Management of Customer Master Data

• Subscriber Account Management
• Charging Contract Management
• Subscriber Mapping Table Management
• Subscriber Range Table Management
• Export and Import of Customer Data
• Charging Contract Operational Status Management

Customer Data Migration

• Prepaid Account State Management
• Charging Contract State Management

Business Processing

• Charging
• Recharging
• Refilling
• Activation
• Allowance Management
• Business Process Management

Restricted Services

Some services and operations are provided to be used by other SAP applications. They are not aimed to be used in an implementation project:

• Data Export Management to SAP PSI
• Transport of Catalog Data

These services are released and supported by SAP for restricted consumption only.

Technical Details

Technical details of SOAP messages are included in this documentation for all the service operations. They describe the structure and the content for each message types. The formats of all the elements of the messages are detailed.

• An envelope defines an XML document as a SOAP message and represents its root
• A header contains particular information: see WS-Addressing, wsse (in SAP Security Guide), SAP Passport.
• A body contains an operation request or a response: the technical information is based on the Web Services Description Language (WSDL) and the associated XML Schema Definition (XSD) both provided by SAP CC.

Consult the SAP CC Security Guide for more information about the WS technical interface, the SOAP over HTTP communication channel, and Web Service Security (WS-Security).

WSDL

Web Services Description Languages (WSDL) are available from a running SAP CC Core Server system from each endpoint. A WSDL is provided for each process component (Web service) and includes the specifications of the SOAP APIs. It refers some XSD fragments necessary for your development tools. During the implementation project phase, you can access online to the relevant WSDL by using the URI of the needed process component(s):

• <WS_ENDPOINT_URI>?wsdl

• <WS_ENDPOINT_URI> is the URI of the endpoint related to a Web service (process component)

Endpoints

Idempotent Web Service Operations

SAP CC provides some idempotent or safe operations via the Web Services technical interface. Idempotency management means that the same repeated invocation of safe Web services has no unintended effects on the service state.

Two different modes of message resubmission are supported by SAP CC 4.1, depending on the service operation:

• Without response caching, which means that if a request is detected as resubmitted to SAP CC, a resubmission detection response is sent back (in this case the original operation response is not available).
  In this mode, while the invocations fail whichever the reason is (authentication, missing prerequisite, and so on), next invocations will be processed again. If an invocation is successfully processed, the next invocations will be successful but not processed again.
• With response caching, which means that if a request is detected as resubmitted to SAP CC, the original operation response is sent back.
  In this mode, while the invocations fail whichever the reason is (authentication, missing prerequisite, and so on), next invocations will be processed again. If an invocation is in progress, the next invocations will not be processed and flagged as in progress. If an invocation is successfully processed, the next invocations will be successful but not processed again.

The idempotency capability of SAP CC is based on the Web Service Addressing (WS-Addressing or WS-A) specification and the availability of the WS-A Message ID (wsa:MessageID element) in the SOAP header. Design and implement the appropriate management of these identifiers. The WS-A Message ID is the unique identifier of a SOAP message. A SOAP message having a MessageID header can be sent to SAP CC several times without any problem.

   <soapenv:Envelope xmlns:sch="http://schema.catalog.ws.highdeal.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
         <wsse:Security soapenv:mustUnderstand="1"
                       xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken wsu:Id="UsernameToken-3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                  <wsse:Username>mylogin</wsse:Username>
                  <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
            </wsse:UsernameToken>
         </wsse:Security>
         <wsa:MessageID>uuid:c623a504-7d63-46d8-b9bf-eed05299043b</wsa:MessageID>
      </soapenv:Header>
      <soapenv:Body>
         <sch:mappingTableCreateRequest>
            <id>myMappingTable</id>
            <mappingTableClassId>myMappingTableClass</mappingTableClassId>
         </sch:mappingTableCreateRequest>
      </soapenv:Body>
   </soapenv:Envelope>

Business Object Models

SAP CC Web Services specify data models of business objects necessary to the service operations. These models relate to the master data (subscriber accounts, ...) and transactional data (chargeable items) managed by SAP Convergent Charging. Functional and technical details (see Data Type) are available from each process component.

Master Data

The master data includes configuration data that determines the charging processing.

Master Data Related to the Product Modeling and Pricing Catalog

• Main Data: Charge Plan Classes, Refill Plan Classes
• Business Data Tables: Mapping Tables, Range Tables

Master Data Related to the End Customers of the Service Provider

The customer master data includes the following configuration data:

• Main Data: Subscriber Accounts, Charging Contracts
• Business Data Tables: Subscriber Mapping Tables, Subscriber Range Tables

Transactional Data

• Incoming chargeable item
• Temporary output chargeable item
• Output charged item

Finding Business Objects

Any find operation defined as an SAP CC Web Service returns all business objects available in the system that match the criteria used to search for a given data model. The number of objects contained in the response message may be large and it may be difficult for calling application to iterate on these objects. To retrieve only subset of matching object set and navigate between these subsets, each find operation also specify standardized elements for requests and responses. This mechanism is called pagination.

Using pagination requires a specific implementation on calling application side. Find operations defined by SAP CC Web Services are stateless and do not store any information about the last page sent back to the calling application. To process pages, SAP CC Web Services use a reference that must be transferred from a find response to the next find request to navigate forward or backward among pages. Requests have to be filled with a fromUniqueId element, which is the reference of the first element of the page and response contains a lastUniqueId element which is the reference of the last object of this page. This lastUniqueId element must be used to go forward to the following page.

To activate pagination mechanism a searchWindow element must be set up in the find operation request. This element defines two children to navigate and configure pagination:

• fromUniqueId: The reference to start pagination from. If it is omitted the initial window of the object set is returned by the SAP CC system (first find operation request). It must be then set in following find operation requests and must be equal to the lastUniqueId element read from the previous find operation response.
• windowSize: The maximum number of objects expected in the find operation response. The SAP CC system returns a subset of the matching object set.

<soapenv:Envelope xmlns:sch="http://schema.catalog.ws.highdeal.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>mylogin</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <sch:chargePlanClassDescriptionFindRequest>
         <chargePlanClassSearchFilter>
            <searchWindow>
               <windowSize>2</windowSize>
            </searchWindow>
            <totalCountRequired>true</totalCountRequired>
         </chargePlanClassSearchFilter>
      </sch:chargePlanClassDescriptionFindRequest>
   </soapenv:Body>
</soapenv:Envelope>
                  

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns3:chargePlanClassDescriptionFindResponse xmlns:ns3="http://schema.catalog.ws.highdeal.com/">
         <status>return</status>
         <totalCount>6</totalCount>
         <lastUniqueId>30637</lastUniqueId>
         <chargePlanClassDescription>
            <id>CP1</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 1</description>
         </chargePlanClassDescription>
         <chargePlanClassDescription>
            <id>CP2</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 2</description>
         </chargePlanClassDescription>
      </ns3:chargePlanClassDescriptionFindResponse>
   </S:Body>
</S:Envelope>
                  

<soapenv:Envelope xmlns:sch="http://schema.catalog.ws.highdeal.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>mylogin</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <sch:chargePlanClassDescriptionFindRequest>
         <chargePlanClassSearchFilter>
            <searchWindow>
               <windowSize>2</windowSize>
               <fromUniqueId>30637</fromUniqueId>
            </searchWindow>
            <totalCountRequired>true</totalCountRequired>
         </chargePlanClassSearchFilter>
      </sch:chargePlanClassDescriptionFindRequest>
   </soapenv:Body>
</soapenv:Envelope>
                  

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns3:chargePlanClassDescriptionFindResponse xmlns:ns3="http://schema.catalog.ws.highdeal.com/">
         <status>return</status>
         <totalCount>4</totalCount>
         <lastUniqueId>30657</lastUniqueId>
         <chargePlanClassDescription>
            <id>CP3</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 3</description>
         </chargePlanClassDescription>
         <chargePlanClassDescription>
            <id>CP4</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 4</description>
         </chargePlanClassDescription>
      </ns3:chargePlanClassDescriptionFindResponse>
   </S:Body>
</S:Envelope>
                  

<soapenv:Envelope xmlns:sch="http://schema.catalog.ws.highdeal.com/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header>
      <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>mylogin</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">********</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <sch:chargePlanClassDescriptionFindRequest>
         <chargePlanClassSearchFilter>
            <searchWindow>
               <windowSize>2</windowSize>
               <fromUniqueId>30657</fromUniqueId>
            </searchWindow>
            <totalCountRequired>true</totalCountRequired>
         </chargePlanClassSearchFilter>
      </sch:chargePlanClassDescriptionFindRequest>
   </soapenv:Body>
</soapenv:Envelope>
                  

<soapenv:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns3:chargePlanClassDescriptionFindResponse xmlns:ns3="http://schema.catalog.ws.highdeal.com/">
         <status>return</status>
         <totalCount>2</totalCount>
         <chargePlanClassDescription>
            <id>CP5</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 5</description>
         </chargePlanClassDescription>
         <chargePlanClassDescription>
            <id>CP6</id>
            <owner>webServicesCatalog</owner>
            <status>released</status>
            <description>Charge Plan 6</description>
         </chargePlanClassDescription>
      </ns3:chargePlanClassDescriptionFindResponse>
   </soapenv:Body>
</soapenv:Envelope>
                  

Service Operation Processing

SAP CC Web Services provide two particular modes for bulk processing: The bundle and mass modes. The bundle or mass operation groups multiple single operations for processing by the connected SAP CC system. All the single operations are the same type. The single operations are sequentially executed.

You implement the operations in bundle mode or in mass mode according to your business requirements and context.

Bundle Mode (All or None)

The bundle operation groups multiple single operations for processing. All single operations are successfully performed or none: The processing stops at the first failed single operation and the modifications done by the previous single operations are canceled in the SAP CC system.

The overall bundle result includes a list of successful single results. In case of business error, the overall result is failed and includes a list of successful but not applied single results and one failed operation. In case of system error, a SOAP fault is replied. No change applies.

The required implementation of the error handling is facilitated: Your application must send again the same request once the issue has been fixed. Each time an error occurs, you must restart from the beginning.

Mass Mode

The mass operation groups multiple single operations for processing. Most of the single operations are successfully performed whatever the failure of certain single operations: The processing is never stopped (except for a system failure) and the modifications done by the previous single operations remain in the SAP CC system.

The overall mass result includes a list of successful or erroneous single results.

• In case of some business errors, the overall result is successful and includes a complete list of successful or erroneous single results and the count of errors.
• If all the single operations fail, then the mass operation fails.

The required implementation of the error handling is intelligent based on the count of individual errors: Your application must be able to take into account the successful and the failed single operations to only send again the relevant single operations later on. All the business errors are immediately listed in the mass result.

SAP Passport Handling

SAP CC Web Services support the SAP Passport technology for the end-to-end tracing feature. See the SAP CC Application Help and the SAP CC Operations Guide for more information about the logging and tracing functions, and performance troubleshooting.

Security

Consult the SAP CC Security Guide to get information on communication security and user rights to perform the service operations described in this documentation.

Configuration

Consult the SAP CC Configuration and Implementation Guide to set up the technical settings of the SAP CC system for the Web Services and to get some recommendations on the implementation activities.

Related Documentation

For more information, see the related product documentation of SAP Convergent Charging in SAP Help Portal.

• SAP CC Error Code Reference (SAP site)
• SAP CC Configuration and Implementation Guide
• SAP CC Security Guide
• SAP CC Application Help