GB992 Open API Map R18.0.1
GB992 Open API Map R18.0.1
GB992 Open API Map R18.0.1
GB992
Release 18.0.1
September 2018
NOTICE
This document and translations of it may be copied and furnished to others, and derivative works
that comment on or otherwise explain it or assist in its implementation may be prepared, copied,
published, and distributed, in whole or in part, without restriction of any kind, provided that the
above copyright notice and this section are included on all such copies and derivative works.
However, this document itself may not be modified in any way, including by removing the copyright
notice or references to TM FORUM, except as needed for the purpose of developing any document
or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules
applicable to copyrights, as set forth in the TM FORUM IPR Policy, must be followed) or as required to
translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its
successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and TM FORUM
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP
RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that
would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to
notify the TM FORUM Team Administrator and provide an indication of its willingness to grant patent
licenses to such patent claims in a manner consistent with the IPR Mode of the TM FORUM
Collaboration Project Team that produced this deliverable.
The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a
claim of ownership of any patent claims that would necessarily be infringed by implementations of
this TM FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license
to such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration
Project Team that produced this TM FORUM Standards Final Deliverable. TM FORUM may include
such claims on its website but disclaims any obligation to do so.
TM FORUM takes no position regarding the validity or scope of any intellectual property or other
rights that might be claimed to pertain to the implementation or use of the technology described in
this TM FORUM Standards Final Deliverable or the extent to which any license under such rights
might or might not be available; neither does it represent that it has made any effort to identify any
such rights. Information on TM FORUM's procedures with respect to rights in any document or
deliverable produced by a TM FORUM Collaboration Project Team can be found on the TM FORUM
website. Copies of claims of rights made available for publication and any assurances of licenses to be
made available, or the result of an attempt made to obtain a general license or permission for the
use of such proprietary rights by implementers or users of this TM FORUM Standards Final
Deliverable, can be obtained from the TM FORUM Team Administrator. TM FORUM makes no
representation that any information or list of intellectual property rights will at any time be
complete, or that any claims in such list are, in fact, Essential Claims.
Table of Contents
NOTICE......................................................................................................................................... 2
Table of Contents ......................................................................................................................... 4
List of Figures ............................................................................................................................... 6
Executive Summary ...................................................................................................................... 6
1. Introduction ........................................................................................................................... 8
1.1. The audience of the API Map ................................................................................................... 8
2. Open Digital API Map Overview .............................................................................................. 9
2.1. Business value of API Map ....................................................................................................... 9
2.2. Principles of API Map ............................................................................................................... 9
2.3. Consistency with API Catalog ................................................................................................. 10
3. Hierarchy of the API & Resource Map .....................................................................................11
3.1. Level 0 Map ............................................................................................................................ 11
3.2. Level 1 Map ............................................................................................................................ 12
3.2.1. Level 1 Map – Current & Deprecrated API’s .............................................................. 14
3.2.2. Mapping between current TM Forum API and Information Framework .................. 22
3.2.3. Level 1 Map – Planned & Future API’s....................................................................... 28
3.2.4. Mapping between planned/future TM Forum API and Information Framework ..... 30
3.3. Level 2 Map ............................................................................................................................ 32
3.3.1. API in Marketing/Sales............................................................................................... 32
3.3.2. API in Product ............................................................................................................ 34
3.3.3. API in Customer ......................................................................................................... 36
3.3.4. API in Service ............................................................................................................. 40
3.3.5. API in Resource .......................................................................................................... 43
3.3.6. API in Engaged Party .................................................................................................. 45
3.3.7. API in Enterprise ........................................................................................................ 48
3.3.8. API in Common .......................................................................................................... 49
4. API Dependency Relation .......................................................................................................53
5. API Map Usage examples .......................................................................................................64
5.1. API Deployment View in Vodafone ........................................................................................ 66
5.1.1. Level 0 of API Deployment View ................................................................................ 67
5.1.2. Level 1 of API Deployment View ................................................................................ 67
5.2. API Deployment View inBT .................................................................................................... 69
5.2.1. Level 0 of API Deployment View ................................................................................ 70
5.2.2. Level 1 of API Deployment View ................................................................................ 70
5.3. API Deployment View in Orange ............................................................................................ 71
List of Figures
Figure 1 – Level 0 Map ......................................................................................................................................... 12
Figure 2 – Level 1 Map ......................................................................................................................................... 13
Figure 3 - API Map Level 1 (Current/Existing & Deprecated) ............................................................................ 14
Figure 4 - API Map Level 1 (Planned &Future) ................................................................................................... 29
Figure 5 – Legend ................................................................................................................................................. 32
Figure 6- API in Marketing/Sales ......................................................................................................................... 32
Figure 7 – API in Product ..................................................................................................................................... 34
Figure 8 – API in Customer .................................................................................................................................. 36
Figure 9 – API in Service....................................................................................................................................... 40
Figure 10 – API in Resource ................................................................................................................................. 43
Figure 11 – API in Engaged Party......................................................................................................................... 45
Figure 12 – API in Enterprise ............................................................................................................................... 48
Figure 13 – API in Common ................................................................................................................................. 49
Figure 14 – DPRA Platform template .................................................................................................................. 64
Figure 15 – Platform meta-model....................................................................................................................... 65
Figure 16 – Vodafone Platform Architecture ..................................................................................................... 66
Figure 17 – Level 0 Deployment view ................................................................................................................. 67
Figure 18 – Level 1 Deployment view ................................................................................................................. 68
Figure 19 – Level 1 Deployment view (Current APIs)......................................................................................... 68
Figure 20 – Level1 Deployment view (Planned & Future API's) ........................................................................ 69
Figure 21 – BT Platform Architecture ................................................................................................................. 69
Figure 22 – Level 0 BT API Deployment view ..................................................................................................... 70
Figure 23 – Level 1 BT Deployment view............................................................................................................ 70
Figure 24 – Level 1 BT Deployment view (Current API’s) .................................................................................. 71
Figure 25 – Level 1 BT Deployment view (Planned & Current) ......................................................................... 71
Figure 26 – Orange’s business functionality ....................................................................................................... 72
Figure 27 – Orange’s level 0 of API Deployment View....................................................................................... 73
Figure 28 – API used by Orange are mapped to the platform layers................................................................ 74
Figure 29 – APIs are mapped to the platform layers ......................................................................................... 75
Figure 30 – Level 0 of Huawei’s deployment view............................................................................................. 76
Figure 31 – Level 1 of Huawei’s deployment view............................................................................................. 77
Executive Summary
In this increasingly digitized world, IT technology is connecting more and more people. This
technology brings the enterprises into a dynamic, distributed environment and delivers
business value on multiple channels including desktops and mobile devices. Since the
complexity and scale is unprecedented, more openness and agility is required during
innovation and competition in today’s economy. The industrial trend has shown clearly that
enterprises must provide more visibility to their APIs (Application Programming Interfaces)
to facilitate open integration.
The TM Forum knows the importance of APIs and a group of open digital API definitions has
been made. To date, those definitions have been based on the contributions of discrete API
initiatives.
The API Map is intended to show the complete landscape of all the necessary APIs in a
telecommunications ecosystem. It can guide the Service Providers or other large
Enterprises to construct the ecosystem to attract DSP partners and integrating with them
or as a basis of customization for individual partnerships.
The API Map will also uncover the future-oriented planning for potential new business APIs.
In the years hereafter, those API definitions will be explored and the efforts to build them
are encouraged fully.
The use of a standard API Map will facilitate the understanding of the interoperability
between Service Providers and their partners and provide additional benefits for the
enterprises such as:
- With a unified API Map, an enterprise can experience:
o Lower software integration costs, as application vendors converge on standardized
exposure of capabilities
o Increased portability of applications
o Improved interoperability within and between business functions
o Easier upgrade and exchange of system components.
- By exposing IT capabilities as APIs, we will find new partnership models to enhance our services.
1. Introduction
This document provides an overview of the TM Forum API Map and its inheritance from the
TM Forum API done to-date.
Its purpose is to present the value of the TM Forum API Map which shows the complete
picture of business related API for the first time.
It is structured as follows:
- An overview of the Open Digital API Map:
o The business value it can provide
o The principles of the API Map
- A hierarchical taxonomy of the API Map
- A description of all the current TM Forum APIs in the API Map
- A summary of planned and future APIs which are in development now or need to be developed in
future within the TM Forum.
There are a number of industry-standard principles that guide the construction of good APIs,
such as:
• Abstraction: Reflect the “business” service being provided, hiding the implementation.
• Loose-coupling: Do not expose any technical dependencies/intimate knowledge of the underlying
implementation.
• Reusability: APIs are defined with re-use in mind (even for unknown future use-cases).
• Discoverability: Service contracts can be effectively communicated and interpreted.
• Developer-friendly: APIs can be consumed with minimal effort/cost.
Especially for the API in this Map, the division and position of the APIs also follow the
distinct organization principles, as follows:
• Each API belongs to one or several Level 0 domains rooted in TMF Information Framework (SID)
model.
• The domain of the API is determined by the relevant Information Framework ABE which is the base
of the main resource of that API.
o If there are multiple Information Framework ABE entities which are depended by one API
resource, the main Information Framework ABE is chosen according to the degree of
correlation between Information Framework ABE and API resource.
o If there are multiple Information Framework ABE entities which are depended by one API
resource, and the Information Framework ABE entities have same degree of importance
for this API resource, such API should be placed in all relevant domains.
o The relationship between API and Information Framework will still be verified via business
process (As shown in Chapter 4, this will be done in the future).
• The existing published TMF API is expected to keep as it is currently. Any change to the existing APIs
should be discussed and agreed.
• The API should contain the tightly-related resources for the same purpose. The loose-coupled
resources need to be divided into different API.
• The purpose of API and exposed resources in the API should not be duplicated.
You can therefore consider the API Map as a central catalog with a number of framework-centric views,
expressed as mappings into that catalog.
Multiple views of the API Map are required to address different concerns and to represent different
viewpoints.
The Information view of the API Map shows the API and API resources mapped to the Information
Framework data domains and ABE’s. This is useful to understand what data is managed through which API’s.
The Business Process view of the API Map shows the API’s in business context. This is useful to understand
how API’s are used to support the business processes of an organisation.
The ‘Information view’ of the API Map is organized in multiple levels:
- Level 0: the standard Frameworx business domains
- Level 1: The main TM Forum APIs, typically the primary resource, and aligned to TMF Information
Framework ABEs.
- Level 2: the component resources exposed within the API.
Enterprise The Enterprise domain provides support and sets policy for the overall business,
enterprise or Service Provider. It also includes activities that are common to all
enterprises across all industries such as accounting and human resource
management.
Common The common domain is of different nature from the above defined ones as the
processes, information data and applications described there do not necessarily
have relationships.
Level 1 is the main TM Forum APIs and aligned to TMF-Information Framework ABEs.
Each level-0 part in the API Map shall contain the APIs which are based on the enterprise business
operation requirements.
An API can contain a group of API resources which are aggregated to accomplish the same business
purpose. API resource is mapped in Level 2 of the API Map.
Note:
1) Product Ordering API, SLA API, Activation and Configuration, , Payment Management API appear in
multiple domains due to the Information Framework mapping relationship.
2) “Address” API will be renamed as “Geographic Address”
Note: Product Ordering API, SLA API, Activation and Configuration API appear in multiple domains
due to the SID mapping relationship.
To date, the TM Forum Open Digital API has delivered or started defining the following APIs:
- Promotion API
Promotion is the online incentive which provides discount, gift or other substantial
stimulation to encourage more consumption according to the purchased offering.
This API provides a shopping cart which is used for the temporarily selection and reservation of
offerings in e-commerce and retail purchase.
The Product Ordering API provides a standardized mechanism for placing a product order with all of
the necessary order parameters. The API consists of a simple set of operations that interact with
CRM/Order negotiation systems in a consistent manner. A product order is created based on a
product offering that is defined in a catalog. The product offering identifies the product or set of
products that are available to a customer, and includes characteristics such as pricing, product
options and market.
The product order references the product offering and identifies any specific requests made by the
customer.
The Product Catalog Management API allows the management of the entire lifecycle of the catalog
elements, the consultation of catalog elements during several processes such as ordering process,
campaign management and sales management.
A loyalty program product specification is a detailed description of a loyalty program made available
externally in the form of a Loyalty Product to Loyalty Program Members. A loyalty program product
specification defines one or more Loyalty Rules that have to be checked in order to identify the
actions to apply
The Trouble Ticket API provides a standardized client interface to Trouble Ticket Management
Systems for creating, tracking and managing trouble tickets among partners as a result of an issue or
problem identified by a customer or another system. Examples of Trouble Ticket API clients include
CRM applications, network management or fault management systems, or other trouble ticket
management systems (e.g. B2B).
The API supports the ability to send requests to create a new trouble ticket specifying the nature and
severity of the trouble as well as all necessary related information. The API also includes mechanisms
to search for and update existing trouble tickets. Notifications are defined to provide information
when a ticket has been updated, including status changes. A basic set of states of a trouble ticket has
been specified to handle ticket lifecycle management.
The SLA API provides a standardized interface for SLA life cycle Management (SLA Negotiation, SLA
configuration SLA Activation/enforcement, SLA Operations, SLA violation / consequence handling,
SLA reporting) between a Customer and a Service Provider which provides offers (product with
attached SLA in its catalog) the customer can discover, browse, trigger and order.
It also will be also useful in a multi-partner environment where exchanging SLA is needed in order to
allow rapid and efficient SLA life cycle management across partners’ environment. From SLA
perspective, duties and rights are assigned to each actor & associated roles mainly in the case where
a service is composed of various components brought by different partners within federation or / and
syndication models.
The Performance Management API provides standardized mechanism for performance management
such as creation, partial or full update and retrieval of the resources involved in performance
management (Measurement Production Job, Measurement Collection Job, and Ad hoc Collection). It
allows also notification of events related to performance.
The Customer Management API provides standardized mechanism for customer and customer
account management, such as creation, update, retrieval, deletion and notification of events.
Customer can be a person, an organization or another service provider who buys products from an
enterprise. Customer management API allows management of identification and financial
information about him.
The Party Management API provides standardized mechanism for party management such as
creation, update, retrieval, deletion and notification of events.
Party can be an individual or an organization that has any kind of relation with the enterprise.
Party is created to record individual or organization information before the assignment of any role.
For example, within the context of a split billing mechanism, Party management API allows creation
of the individual or organization that will play the role of 3rd party payer for a given offer and, then,
allows retrieval or update of their information.
The Usage management API provides standardized mechanism for usage management such as
creation, update, retrieval, import and export of a collection of usages.
This API will be extended to include more services relevant to usage charging.
The Product Inventory API provides standardized mechanism for product inventory management
such as creation, partial or full update and retrieval of the representation of a product in the
inventory. It also allows the notification of events related to product lifecycle.
For example, product inventory API can be used to retrieve products owned by a customer or update
the status of an installed product.
The Activation and Configuration API allows the user to retrieve, create, update, delete services and
retrieve the monitor resource used to monitor the execution of asynchronous requests on specific
resource.
The Privacy Management API provides the management for the customer privacy information and
preference.
It provides standardized mechanisms for managing an onboarding process. The intention for
onboarding process in the Digital Ecosystem is to have a lightweight approach similar to an end-user
signing-on to terms and conditions for downloadable applications. The interface will provide
onboarding that identifies that a new API would be needed to automate the onboarding process. The
onboarding of the “Party”, the role can be Partner, Supplier, Developer, etc. The onboarding of the
“Services” could be product offerings.
This API provides standardized mechanism for managing agreements, especially in the context on
partnerships between partners.
Service Qualification API is one of the Pre-Ordering Management APIs. Service Qualification API goal
is to provide service availability at Customer location.
- Appointment API
The Appointment API is one of the Pre-Ordering Management APIs. The appointment API provides a
standardized mechanism to book an appointment with all the necessary appointment characteristics.
First, the API consists in searching free slots based on parameters, as for example a party. Then, the
appointment is created. The appointment has characteristics such as nature of appointment, place of
appointment.
- Quote API
The Quote API is one of the Pre-Ordering Management APIs. The customer Quote API provides a
standardized mechanism for placing a customer quote with all of the necessary quote parameters.
Prepay Balance Management API manages the balance, recharge (top-up) and transfer resources.
This API provides Quality Management for the certain service. It enables easy integration of Service
Quality Management applications and client applications within the Digital Eco-system, where
Service Quality Management application may reside in one enterprise and client applications may be
in multiple other Enterprises.
This API provides test procedure for the certain service. The Service Test API provides a standardized
mechanism for placing a service test with all of the necessary test parameters.
This API provides the control mechanism for the change of the service. Change Management process
is to respond to the customer’s changing business requirements while maximizing value and reducing
incidents, disruption and network. The Change Management API provides the standard integration
capabilities between external applications and Change Management Application.
This API allows the management of the entire lifecycle of the catalog elements, the consultation of
catalog elements during service processes.
- Service Inventory
The Service Inventory API can be used to query the service instances for a customer via Self Service
Portal or the Call Centre operator can query the service instances on behalf of the customer while a
customer may have a complaint or a query.
The Service Ordering API provides a standardized mechanism for placing a service order with all of
the necessary order parameters. It allows users to create, update & retrieve Service Orders and
manages related notifications.
This API provides the order implementation on the resource to change or allocate the resource to
meet the request of product order and service order.
This API is to be used for provisioning of components in support of cloud services. The components
may be virtualized or physical.
This SPM API is used for the service providers (Defined as the Middle B) to manage the service
problems in their service area. Service problem is generated based on the information declared by
Middle B or the event information notified from infrastructure providers (Defined as the First B) who
provide the infrastructure of cloud or network.
The Resource Catalog Management API REST specification allows the management of the entire
lifecycle of the Resource Catalog elements, the consultation of resource catalog elements during
several processes such as ordering process, campaign management, and sales management.
It provides the operations to synchronize documents and document versions across systems. It also
provides operations for uploading documents by Users as well as for viewing of documents online.
This API supports the frequently-used payment methods for the customer to choose and pay the
usage, including voucher card, coupon and money transfer.
This API provides the capability to manage the entity catalog API. The catalog entity item
could be an entity, entity specification, product offering, service candidate, or resource
candidate that appears in an entity catalog.
- Recommendation API
Recommendation API is used to recommend offering quickly based on the history and real-
time context of customer. It is a real-time and personalized recommendation API. It is usually
provided by e-commerce or BSS, CRM system in omni-channel.
This API provides also operations to find and retrieve the details of applied customer billing
rates presented on a customer bill.
And this API is also used to manage the creation request of a customer bill in real-time (on
demand).
The Geographic Address Management API provides a standardized client interface to an Address
management system.
This API covers the operations to manage (create, read, delete) sites that can be associated to a
customer, an account, a service delivery or other entities.
This API defines a Site as a convenience class that allows to easily refer to places important to other
entities, where a geographic place is the entity that can answer the question “where?”, allowing to
determine where things are in relation to the earth's surface, and can be represented either in a
textual structured way (geographic address) or as a geometry referred to a spatial reference system
(geographic location).
A Geographic Location is a point, a surface or a volume defined by geographic point(s). These points
should be associated with accuracy and a spatial reference.
The geographic location API provides a standardized client interface to a location management
system.
- Communication API
Communication message means a notification approach in the format of a message which can be
dispatched (sent) to the certain user by the system with the content which can be felt and
understood by the recipient. The user can be either a final customer or a customer service agent. The
message can reach the customer in different interaction channels, including: email, short message,
mobile app notification (push).
Communication API performs the following operation on the resource of “Communication Message”.
There are two types of operations provided in this API. One is the management of the request
message body. Another is for sending the communication message to the customer.
The usage consumption API allow to view at a given point the balance and the consumption counters
of the various buckets (SMS, Voice, Data for example) that one or more user(s) consume with each of
his devices, according to the purchased offers and options.
A usage consumption report retrieves the data related to these balances and various consumption
counters and calculated at the time of the request by the server.
So, the API allows to retrieve usage consumption report with information about balances and
consumption counters for a given criteria: subscribed offer or option, a given device or a user for
example.
The Performance Thresholding API provides a standardized client interface to Service and Resource
Performance Management Systems for manipulating (create/update/delete)
threshold/violation/exception rules. It enables alarms/notifications on exceptions and scheduling of
threshold/violation/exception evaluation.
The API supports the ability to define a Threshold as a set of rules that determine when to raise an
alarm and when to clear it for various severity levels. Correspondingly, for each rule used for raising
alarms, the expected alarm fields of the Threshold Crossing Alarm (TCA) can be set over the interface.
The API will support Performance Thresholds creation deletion and query.
Telco companies often send goods to customers. Shipment information can be provided to them, so
they can be aware of when things were shipped and when they will arrive. Typically, Telco’s use
different delivery companies to deliver things on their behalf and this API intends to abstract the end
developers from that complexity by providing a single interface. A Shipment Tracking captures
information about the current status of the shipment, the past checkpoints and the estimated arrival
date. Via this API, tracking information can be retrieved by providing an order Id or the shipping
company’s tracking id.
The mapping between the current TM Forum API and Information Framework ABE is described as the
table below. The above figure is made based on the mapping results. The policy is that any API will be
put in its main domain.
If one API covers several domains besides Customer and Engaged Party together, the main domain
will be decided by the business. If one API covers Customer and Engaged Party together, the main
domain will be decided by the business also but generally Engaged Party is prior to Customer.
33.
Product Domain ::Product Offering
Promotion API Promotion Product
ABE::Product Promotion ABE
Customer Domain::Customer Order
34. Shopping Cart ABE
Shopping Cart Customer
API Engaged Party Domain :: Party
Order ABE
Common Business Entities:: User
35. User Roles & UserRole
and Roles ABE Common
Permissions
Permission No existing ABE for mapping
Common Business Entities
Entity Catalog Domain ::Catalog ABE :: Entity
Catalog ABE
Category No existing ABE for mapping
Common Business Entities
Entity Catalog Item Domain ::Catalog ABE :: Entity
Catalog ABE
36. Entity Catalog Common Business Entities Common
Management Entity Specification Domain :: Root Business Entities
ABE
Common Business Entities
Association Domain :: Root Business Entities
ABE
Common Business Entities
Association Specification Domain :: Root Business Entities
ABE
Common Business Entities
37. Document Domain :: Root Business Entities
Document Common
Management API ABE
No existing ABE for Document itself
Engaged Party Domain :: Party
Voucher Revenue ABE :: Party Bill Collection
ABE :: Party Payment ABE
Engaged Party Domain :: Party
38. Payment
Card Payment Revenue ABE :: Party Bill Collection Engaged Party
Methods API
ABE :: Party Payment ABE
Engaged Party Domain :: Party
Money Transfer Revenue ABE :: Party Bill Collection
ABE :: Party Payment ABE
Engaged Party Domain:: Additional
Party Account
Party Entities ABE
Customer Domain::Customer ABE
Billing Account Engaged Party Domain::Additional
39. Account Party Entities ABE Engaged Party
Management API
Engaged Party Domain:: Party
Settlement Account Revenue ABE :: Party Settlement
ABE (preliminary)
Financial Account Enterprise Domain :: Finance ABE
Note: Product Ordering API, SLA API, Activation and Configuration, Payment Management API appear
in multiple domains due to the Information Framework mapping relationship.
The following is a view of all the potential business APIs Level 1 Map that briefly describes
each resource for the potential business API. In the years hereafter, those API definitions
will be further explored and the efforts to build them are encouraged fully for all the
industry.
Note: More details about the future API shall be supplemented when the API is confirmed.
Currently the brief descriptions of those APIs are given in this chapter for understanding.
This list is the guide for the API development in the future. The details of these APIs are expected to
be found in the separate API specification.
Marketing/Sales
- Marketing API
This API is used to manage the campaign to represent the carrier-initiated marketing activity
which aims at the better recognition about its brand and offerings by the market.
- Sales Management API
This API provides interfaces for Sales Lead, Sales Opportunity, Sales Quote and the other
management capabilities to support the sales activities to build relationship with the
prospect customer who could be a person or organization that has an interest in the goods
and/or services and possibly become the actual customers with one or more Subscriptions.
- Sales Organization Management API
Provides the management capability for sales organization. The structure of a sales
organization identifies how an organizations sales department is organized in order facilitate
the organizations sales growth.
Product
- Product Stock Management API
This API checks availability of products in stock, and provides adjustment, reservation for the stock.
Customer
- Customer Preference API
It provides the capabilities to manage the customers’ preference for their information access
and control, including permission and profile.
Service
- Digital Service Management API
Provides the management capabilities to manage the operating lifecycle of digital services –
i.e. it exposes a simple “Operations API” defined in the “Digital Services Reference
Architecture (DSRA)”. This includes the endpoints to manage the lifecycle of a digital service
and their state and to manage alarms, SLAs, thresholds and related metrics in the context of
application delivered and consumed through digital channels
Resource
- Topology API
This API is used to support application to have an up to date and accurate view of the topology and
the vertexes and edges required to provide the service. At the same time, topology API could be used
to feed other applications for value-adding – such as a layer network view for provisioning, or a
vertical slice for assurance.
Enterprise
- Retail Premise API
This API is the management of the enterprise routine tasks, including project, purchase order
and retail premises information enquiry.
- Workforce Management API
This API manages work force which supports and execute the manual work that can be sent
to a workforce staff team to process.
Common
- Customer Insight API
This API is the statistics and business intelligence capabilities for the enterprise data.
- Project API
It is the management of internal enterprise project.
- Event Management
Event is any of the action triggered by the human or the system which requires the notification to the
other system.
- Experience Management
Experience is the data and their impact which reflect the feeling of the user of the system. Based on
the experience, the user can give judgment to the system about its usability.
The mapping between the planned and future TM Forum API and Information Framework ABE is
described as the table below.
Market/Sales Domain::
Sales Lead
Contact/Lead/Prospect ABE
Market/Sales Domain::
Sales Opportunity
Contact/Lead/Prospect ABE
Sales
2.
Management Sales Task N/A Market/Sales
API
Market/Sales Domain::
Sales Account
Contact/Lead/Prospect ABE
Market/Sales Domain::
Sales Partner Account
Contact/Lead/Prospect ABE
Sales
3. Organization Sales Channel Market/Sales Domain:: Sales
Market/Sales
Management Management Channel ABE
API
Product Stock No existing ABE for mapping
Product Stock
4. Product Stock
Management No existing ABE for mapping Product
Adjustment
API
Product Stock
No existing ABE for mapping
Reservation
6. Customer 360
Customer 360 View Customer::Customer ABE Customer
View API
Digital Service
7.
Management Digital Service Service ::Service ABE Service
API
8. Common Business Entities
Topology API N/A Resource
Domain :: Topology ABE
9. Purchase
Purchase Order Engaged Party Domain :: Party EngagedParty
Order API
Order ABE
10. Retail Enterprise Domain:: Enterprise
Retail Premise Enterprise
Premise API Effectiveness ABE
Workforce
11. Enterprise Domain ::Workforce
Management Work Order Enterprise
ABE
API
12. Common Business Entities
Project API Project Common
Domain:: Project ABE
13. Customer Check Customer Credit Engaged Party Domain ::
Common
Insight API Rating Additional Party Entities ABE
Level 2 shows the API which inherits from the current TM Forum API or extends on the base of TM
Forum API.
Figure 5 – Legend
Product attributes are its identifier, name, description, status, related product offering,
characteristics, specification, related billing account and parties, location, realized service and
price information
- Promotion API
Promotion (as API resource)
Promotion is the online incentive which provides discount, gift or other substantial
stimulation to encourage more consumption according to the purchased offering.
- Recommendation API
Recommendation (as API resource)
Recommendation is a type of automated (typically, conditional) system action to determine
which products offerings to be presented as up-sells, cross-sells, and related products to each
customer segment based on customer and session specific information. The design-time
offers, and product recommendations may come from Marketing and Catalog. The run-time
evaluation and presentment will be executed with contextual/session information. Normally,
it supports the recommendation of the offer which is proper for the customer, provides Up-
sell and cross-sell based on contextual and catalog rules.
set of products that are available to a customer, and includes characteristics such as pricing,
product options and market.
- Product Offering Qualification API
Product Offering qualification (as API resource)
It checks whether the offering can be delivered to a specific location.
Service provider execute Product-Offering Qualification task to get the customer location
Feasibility include Commercial and Technical eligibility.
- Payment Management
Payment (as API resource)
The Payment resource represents a performed payment. It contains both information about
the payment and the payment method used to perform it. That information could be used
for reconciliation purposes with payment gateways, to centralize information of several
payment gateways in a single place, to keep track of payment methods used in case refunds
must be made, etc.
Refund (as API resource)
Operations over refund resource are expected to be performed by a privileged user/system
(such as an admin)
- Customer Bill API
Customer Bill(as API resource)
A billing account is a detailed description.
The customer bill is linked to one or more documents that can be downloaded via a provided
url.
Applied Customer Billing Rate
A customer bill displays applied billing rates created before or during the billing process
Customer Bill On Demand
This resource is used to manage the creation request of a customer bill in real-time (on
demand).
- Shopping Cart API
Shopping Cart (as API resource)
The shopping cart is widely used for the temporarily selection and reservation of offerings in
e-commerce and retail purchase.
- Quote Management API
Quote (as API resource)
It provides a mechanism for placing a customer quote based on a product offer in a catalog
It identifies available product to a customer w/ pricing, product options and agreement
- Prepay Balance Management API
Bucket Balance (as API resource)
The Bucket Balance resource represents and tracks the amount remained or owed for a
certain type of service by certain customer. The balance is associated to a specific product or
reference to a product (i.e.: a commercial id such as an msisidn) and a service type .This
resource covers the main attributes defined in class CustomerAccountBalance defined in SID
(validFor, remainedAmount).
Accumulated Balance(as API resource)
The Accumulated Balance resource represents and tracks the aggregated amount remained
or owed in certain account which is owned by certain customer for a set of buckets. This is an
optional resource that may be useful to allow a consumer understand the specific balance for
a given service/product, aggregating all the buckets that hold balance for that service (e.g.:
acquired by the customer, offered for free as a promotion by the operator, granted by
another customer, ….) without requesting one by one the balance in all the buckets and then
perform the addition.
Balance Top up Request (as API resource)
The resource is a detailed description of a recharge operation requested over a subscription.
Balance Transfer Request (as API resource)
The resource is a detailed description of credit transfer operation requested between two
subscriptions.
Balance Adjustment Request (as API resource)
The resource is a detailed description of credit adjustment operation performed on a given
subscriptions.
Balance Activity(as API resource)
The Balance Activity resource is a detailed description of a specific balance-related action
that has happened over a given bucket balance. Typically, a recharge/transfer/adjustment
request creates one activity, but a request for an auto-top-up operation actually triggers
multiple periodic balance-related activities.
Balance Reserve Operation(as API resource)
The Balance Reserve Operation resource is a detailed description of a balance reserve
operation requested over a bucket (defined by a specific product or reference to a product
(i.e.: a commercial id such as an msisidn) and a service type)
Balance Unreserve Operation(as API resource)
The Balance Unreserve Operation resource is a detailed description of a balance unreserve
operation requested over a product
Balance Deduct(as API resource)
The Balance Deduct task resource is a detailed description of deduction operation. If
balanceReserve Resource ID is contained in the deduct request message, the reserved
balance will be performed deduct operation (if part of the reserved balance is deducted, the
remaining amount will be released); if balanceReserve Resource ID is not contained in the
deduct request message, the balance will be deducted directly.
- Line “3”: Ordering of a new simple Service that needs (is supported by) another already
owned Service
A Service Candidate is an entity that makes a Service Specification available to a catalog. A Service
Candidate and its associated Service Specification may be published - made visible - in any number of
Service Catalogs, or in none.
Service Specification (as API resource)
Service Specification is a class for representing a generic means for implementing a particular type of
Service.
Service is an abstract base class for defining the Service hierarchy. All Services are characterized as
either being possibly visible and usable by a Customer or not. This gives rise to the two subclasses of
Service: Customer Facing Service and Resource Facing Service.
A service test specification describes the service test in terms of parameters to be configured and
measures to be taken.
Service Test Specification (as API resource)
A service test is an entity that exists that exists for a controlled test invocation on a service. The
service test is executed according to a schedule and contains service test configuration parameters
that are to be applied at execution time, and service test measures that result.
Change Management process is to respond to the customer’s changing business requirements while
maximizing value and reducing incidents, disruption and network. The Change Management API
provides the standard integration capabilities between external applications and Change
Management Application. The API consists of a simple set of operations that interact with Change
Request in a consistent manner. A Change Request is an IT service management discipline. The
objective of change management in this context is to ensure that standardized methods and
procedures are used for efficient and prompt handling of all changes to control IT infrastructure and
Network, in order to minimize the number and impact of any related incidents upon service.
Service level objective is the quality goal for a Service Level Specification defined in terms of
parameters and metrics, thresholds, and tolerances associated with the parameters.
Service Level Specification (as API resource)
A service level specification is a pre-defined or negotiated set of Service Level Objectives, and
consequences that occur, if the objectives are not met.
A Resource Specification is an abstract base class for representing a generic means for implementing
a particular type of Resource. In essence, a Resource Specification defines the common attributes
and relationships of a set of related Resources, while Resource defines a specific instance that is
based on a particular Resource Specification.
- Topology API
The resource of this API is not decided in this version.
Account used for billing or for settlement purposes concerning a given party (an organization
or an individual).
Settlement Account
A party account used for settlement purposes. It includes a description of the structure used
for the settlement (frequency, presentation media, format and so on).
Financial Account
An account of money owed by a party to another entity in exchange for goods or services
that have been delivered or used. A financial (account receivable account/account payable)
aggregates the amounts of one or more party accounts (billing or settlement) owned by a
given party.
- Privacy Management API
Party Privacy Profile (as API resource)
A Party Privacy Profile represents the privacy choices made by a Party Role.
Party Privacy Profile Type (as API resource)
A Party Privacy Profile Type represents a type description for Party Privacy Profiles.
Party Privacy Agreement (as API resource)
A Party Privacy Agreement represents the approval made by the Party about a Party Privacy
Profile.
- Payment Methods API
Payment Method (as API resource)
The Payment Method resource represents an instantiated payment method that can be of
different types. Some fields are common to all types while the method specification details
depend on the type.
- Party Management API
Individual (as API resource)
Individual represents a single human being (a man, woman or child). The individual can be a
customer, an employee or any other person that the organization needs to store information
about
Organization (as API resource)
Organization represents a group of people identified by shared interests or purpose.
Examples include business, department, and enterprise.
A partnership type contains all the information for the setup of a partnership of a given kind.
This includes the list of identified role types for the partnership with the corresponding
agreement specifications.
Note:
Onboarding Management API has strong dependencies with the following management APIs:
- Party Management API: used to query, create, update or delete information on individuals
or organizations that will be onboarded;
- Agreement Management API: used to query, create, update or delete agreements and
agreement specifications. These agreements need to be created and updated when signed
by the involved parties.
- Billing Management API (It will be enriched and renamed as Account Management API in
the future): used to retrieve, create, update or delete different kinds of accounts that made
be needed in the context of the onboarding process, such as billing or settlement accounts
and financial accounts.
- Project API
Project (as API resource)
It is the management of internal enterprise project.
- Usage Consumption
Usage Consumption Report (as API resource)
A usage consumption report enables to know at a given point the balances and the
consumption counters related to various buckets (SMS, Voice, Data for example). It could be
calculated for a device identified by a public identifier (msisidn number for a mobile device
for example or PSTN or VOIP number for a fix device), for a subscribed offer or option or for a
user.
Usage Consumption Report Request (as API resource)
This resource is used to manage the calculation request of a usage consumption report.
- Event Management
The resource of this API is not decided in this version.
- Experience Management
The resource of this API is not decided in this version.
In TM Forum API, some of them depend on the other. Such dependency relationship exists
and impacts the adaptation of API in the digital environment. The recognition of those
dependencies is important and meaningful for the users to understand the priority and
sequence of the API.
Here the API dependencies are listed for the published ones due to the consideration of
maturity and stability of API.
The dependency can be categorized as “internal” and ”external”.
Internal dependency means the resource entities inside the API have dependency
between them, such as “Catalog” resource of “Product Catalog Management API”
depends on “Category” resource of the same API
External dependency means the resource entities of the API have dependency upon
the resource of another API
The value of transformation to a platform model to service providers as explained in the DPRA is that the
platform model can help:
- To unbundle ownership of the infrastructure (e.g. network access or cloud infrastructure) from the
offering of value-added services to consumers
- Promotes disaggregation of network functions (e.g.) which enable the offering of rich and new value-
added composite services
- Allow for the aggregation of service elements from multiple producers to offer new and value-added
services (i.e. service composition across producer boundaries).
Platform based business models can also be used to efficiently leverage an operator's core
assets and provide competitive differentiation.
The service providers are already in the middle of many service chains so have a natural
placement to easily become the curator between producers and consumers of services.
They must transform from a "Producer" mentality to a "Curator" or match maker mentality.
The DPRA is based on 3 key concepts:
- Platforms: Instances are units of deployment defined by enterprises using templates defined by
Standards Defining Organizations (SDO), including the TM Forum.
They are 'Black box like', can be Vendor /Operator specific, allow for internal evolution and
innovation, and whose implementation can be agile and flexible i.e. time varying.
- Platform Capabilities are exposed by a Platform and are the units of integration used to create
composed capabilities from multiple Platform Capabilities / Platforms.
Platform Capabilities define the rules and best practices for using the combination of Open
APIs used to realize them.
- Open APIs which are the units of interoperability that realize Platform Capabilities and can be
conformance and interoperability tested.
Open APIs are standardized and governed by the TM Forum as well as other SDOs.
Digital Platform Reference Architecture shows the relationship between platforms and
API’s.
At Vodafone, the Open APIs are shown in context of Platform instances, a deployment view of the
Open API’s.
The deployment view is the overall illustration of the API’s in the API Map where we show
each API in context of the platform that acts as “system of record” or “authoritative master”
for the associated API resources.
The deployment view of the API’s is aligned with the Customer/Service/Resource view as
the overall business abstractions as below:
In this Level 1 depiction, the API’ from the API Map are mapped to the platform layers above
The Level 1 of API Deployment view is as the following:
The APIs in the planned or future status can be mapped on the deployment view as the
following:
BT’s business functionality has been partitioned into a set of cooperating IT platforms that enables:
- Reusable common capabilities (SDK’s/API’s) – keeping engineering costs down
- Reusable process blocks – consistent customer experience
BT has 26 platforms and 700 systems which drives simplicity and ruthless standardization and is
intended to minimise whole life costs, reduce cycle time for launching new capabilities and facilitate
business agility.
The deployment view of the API’s is aligned with the Customer/Service/Resource view as
the overall business abstractions as below:
In this Level 1 depicted, the API’ from the API Map are mapped to the platform layers above
The Level 1 of API Deployment view is as the following:
The APIs in the planned or future status can be mapped on the deployment view as the
following:
Orange’s business functionality has also been partitioned into a set of cooperating IT platforms
depicted below.
systems of engagement
In Orange architecture:
- Systems of Engagement deals with User Interfaces (UI) sequences to carry out Party
Interactions using APIs. They hold no business process. They are tied to fast evolving
technologies to support Front End portals and Secured APIs exposed to 3rd party systems.
- Systems of Record deals with operational processes. They handle Offers &Products (WHAT?)
built, run and maintained in a Factory (HOW?) that provides the underlying Services (aka CFS)
or physical products, involving Parties (WHO & WHY?).
- Systems of Insights deal with all non-operational and Analytical processes and support the
strategy design. They process information produced by the enterprise to provide various
insights on its activity (including BI, Financial Management, Fraud Management & Revenue
Assurance,…). They perform complex event/data processing (e.g. eligibility assessment) and
interwork with other systems through event publication.
technical repositories and installed Resource base (that is the installed CFS linked with the
technical resources of the solution).
The deployment view of the API’s is aligned with the Party/Offer & Product/Factory view as the
overall business abstractions as below:
Party
platform
factory
platform
In this Level 1 depiction, the API used by Orange are mapped to the platform layers above. They
can be Orange Standard API (in black) or TM Forum standard API (in white).
In this Level 1 depiction, the TMF APIs are mapped to the platform layers above.
The business process is the end to end line which organizes a group of activities for the certain
purpose. When these activities collaborate together to support the accomplishment of the process,
API is necessary for the interactions between the activities. By describing the API used in the steps of
business process, the completeness and consistency of APIs can be verified.
There is wide range of business processes which are adopted in the different domains. The
recommended selection for the process is based on TM Forum Process Framework (eTOM). In this
document, API verifications will be built based on these published outcomes.
The Level 3 of TMF Process Framework is chosen as the benchmark of API verification. The Level 3 is
the standard process which is also used in GB921D for process decomposition. The granularity of
other levels appears improper because they are too high (Level 0/1/2) or too low (Level 4/5).
The section number of Level 2 and Level 3 process is kept in the mapping, so the original TM Forum
Process Framework content can be conveniently found for comparison.
The TMF API relevance to the TMF Process Framework is depicted in three types:
API name
If the Level 3 Process has the corresponding API to support, the name of API is shown in the
mapping table.
API is not defined
If the process may be supported using API from IT system, but the API has not been defined in the
API Map, it is indicated as “API is not defined” so API can be considered in future.
API is not required
If the process does not require API to support, for example, this process is manually handled,
this process is indicated as “API is not required”
Note: this assessment is based on the knowledge until TMF R16.5. New API may be induced in future
for the process which is currently recognized as “API is not required”
Please refer to the spreadsheet for the GB992 Addendum Mapping between API and
Business_Process_Framework. This is the addendum of this document to contain all the details of the
mapping to support the API verification.
7. Administrative Appendix
This Appendix provides additional background material about the TM Forum and this document. In
general, sections may be included or omitted as desired; however, a Document History must always be
included.
7.4. Acknowledgments
This document was prepared by the members of the TM Forum Agile Business and IT team:
o Pierre Gauthier, TM Forum, Editor
o Lester Thomas, Vodafone, Author
o Steve Harrop, Vodafone, Author
o Nicoleta Stoica, Vodafone, Author
o Jingyi Han, Huawei, Author
o Xu Ma, Huawei, Author
o Yiling(Sammy) Liu, Huawei, Author
o Yisong Jiang, Huawei, Author
o Jean-Luc Tymen, Orange, Author
o Cecile Ludwichowski , Orange, Author
o Andreas Polz, Infonova, Author
o Hongxia Hao, Huawei, Author
o Michel Besson, TMF, Author