We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.Apps.BusinessAPIEcosystem - FIWARE Forge Wiki

FIWARE.OpenSpecification.Apps.BusinessAPIEcosystem

From FIWARE Forge Wiki

Revision as of 12:29, 26 September 2016 by Mcp (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Name FIWARE.OpenSpecification.Apps.BusinessAPIEcosystem
Chapter Apps,
Catalogue-Link to Implementation Business API Ecosystem
Owner UPM, Francisco de la Vega


Contents

Preface

Within this document you find a self-contained open specification of a FIWARE generic enabler, please consult as well the FIWARE Product Vision, the website on http://www.fiware.org and similar pages in order to understand the complete context of the FIWARE platform.

Copyright

  • Copyright © 2016 by UPM
  • Copyright © 2016 by TM Forum

Legal Notice

Please check the following FIWARE Open Specification Legal Notice (implicit patents license) to understand the rights to use these specifications.


Overview

The Business API Ecosystem GE is a joint task force between the TMForum and FIWARE in order to provide a standard set of APIs for enabling the management and monetization of different kind of assets, involving a wide variety of partners, during the whole service life cycle, from offering creation to its charging, accounting and revenue settlement and sharing. In this regard, the Business API Ecosystem GE is mainly responsible for managing offerings and sales and provides support for:

  • The publication of new products and offerings.
  • The acquisition of these products and offerings.
  • The offering payment.
  • The billing management of acquired offerings.
  • The access to all purchased services.
  • The download of software if the offering is part of a downloadable service.
  • The shipment tracking if the offering describes a physical product.
  • The distribution of revenues between all the involved stakeholders.
  • The management of service usage information in order to enable usage-based models


The resulting features constitute a list of the requirements that an implementation of the Business API Ecosystem GE have to satisfy. They are defined below.

  • The Business API Ecosystem GE is responsible for managing offerings. To do this, it supports the registration of products and offerings, which are published by a seller.
  • As there is no generic enabler that stores code, the Business API Ecosystem GE offers an endpoint from which it is possible to download any resources that are part of a purchased and downloadable service.
  • The Business API Ecosystem GE offers a web portal for visualizing, searching and acquiring offerings. Additionally, this portal allows sellers to manage their orders.
  • When a customer decides to acquire an offering via the Business API Ecosystem GE, it manages offering payment, contacts the service provider to notify her the acquisition of the offering, and makes sure that the customer is able either to access the digital service or to track the shipment of the acquired physical product.
  • For some digital services (such as APIs) the Business API Ecosystem GE offers an endpoint to receive accounting information in order to charge customers periodically based on their consumption for those offerings who have defined a usage-based price plan.

Basic Concepts

User model and roles

Taking into account the different functionalities provided by Business API Ecosystem GE, it is necessary to define a model that controls the privileges and possible interactions of Business API Ecosystem GE users. Note that the Identity Management GE is the component in charge of maintaining information about users and roles in the FIWARE platform. Therefore, the Business API Ecosystem GE relies on the Identity Management GE to manage users and roles.

Users of the Business API Ecosystem GE must have at least one and may have any number of roles. The user roles defined depending on the privileges and possible interactions with the Business API Ecosystem GE are as follows:

  • Seller: This role has the option of publishing offerings.
  • Customer: This role has the option of acquiring an offering. (by default).

The Identity Management GE, not the Business API Ecosystem GE, is responsible for managing which role a user plays. It simply notifies the Business API Ecosystem GE of the role that users are playing at any time.

Business API Ecosystem Architecture

The figure below shows the Business API Ecosystem GE architecture, which is divided into a series of independent APIs arranged by a component called “APIs Orchestrator”. This orchestrator is the one in charge of applying the business logic as the independent APIs lack of it. Once that the orchestrator receives a (HTTP) request, the logic is applied and then the request is redirected to the appropriate API.

In addition to orchestrate the different APIs, the orchestrator also provides a web portal intended for final users (those without REST knowledge) to offer them an easy and guided way to sell and purchase products. However, other systems should make direct use of the REST APIs offered by the orchestrator to access the different services provided by the Business API Ecosystem GE.


Business API Ecosystem GE architecture


Among all the existing APIs, there are some which have been developed by the TMForum. Concretely:

  • The Billing Management API provides standardized mechanisms for billing account, bill item and settlement note advice management either in B2B or B2B2C contexts.
  • The Customer Management​ API provides a standardized mechanism for customer and customer account management, such as creation, update, retrieval, deletion and notification of events.
  • The ​Party Management​ API provides a standardized mechanism for party management such as creation, update, retrieval, deletion and notification of events. A Party can be an individual or an organization that has any kind of relation with the enterprise.
  • The Product Catalog Management API provides a standardized solution for rapidly adding partners’ products to an existing Catalog. It brings the capability for Service Providers to directly feed partners systems with the technical description of the products they propose to them.
  • The Product Inventory Management 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.
  • 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 Usage Management API provides standardized mechanism for usage management such as creation, update, retrieval, import and export of a collection of usages. The API manages both rated and non-rated usage. For example, it allows a service provider:
    • To retrieve usage generated by a partner service platform in order to rate it
    • To provide rated usage to a partner for consumption follow up purposes.


Additionally, there are some extra modules intended for actually charging and sharing the revenues between all the interested stakeholders using the information included in the different APIs. Concretely:

  • The Charging Management provides the charging functionality to the system. In this regard, this module is the one in charge of contacting with one or multiple charging platforms (such as PayPal, etc.) and performing the required actions to charge the users for acquiring or using the products provided by the different sellers. In addition, this module is also responsible for managing the lifecycle of digital products, activating them when consumers acquire them or deactivating them when the subscription is cancelled.
  • The RSS Management API provides the functionality for sharing the different revenues derived from the usage of the platform. On this point, this API will allow to create different revenue sharing models so the different stakeholders will be able to distribute the revenues in a flexible way.


Finally, it can be seen that the Business API Ecosystem GE is also connected with some external systems:

  • Identity Management GE: to authenticate users and obtain their information as well as their different roles.
  • Payment Platform: to charge users every time they acquire one or more offerings.
  • Accounting Proxy: to obtain usage information of all the services (i.e. APIs, etc.) managed by the Business API Ecosystem GE so users can be charged based on the amount of resources (i.e. time, bytes, etc.) consumed.

Data Model

Party Management API

Individual: represents a physical person.

  • Birth Date
  • Country Of Birth
  • Death Date
  • Family Name: Last name
  • Formatted Name: A formatted name useful for specific contexts (Chinese, Japanese, Korean, …)
  • Full Name: Full name flatten (first, middle, and last names)
  • Gender
  • Given Name: First name
  • ID: Unique identifier for the individual
  • Location: Temporary current location of the individual (may be used if the individual has approved its sharing)
  • Marital Status: married, divorced, widow, …
  • Middle Name
  • Nationality
  • Place Of Birth: An hyperlink to the place of birth
  • Status: Status of the individual - Initialized, Validated, Deceased
  • Title: Useful for titles (aristocratic, social, …) : Pr, Dr, Sir, …
  • Characteristic: describes the characteristics of the individual such as individual hobbies, center of interests.
    • Name: Name of the characteristic
    • Value: Value of the characteristic
  • Contact Medium: indicates the contact medium that could be used to contact the customer.
    • Preferred: If true, indicates that is the preferred contact medium
    • Type: Email address, telephone number, postal address
    • Valid For: The time period that the contact medium is valid for
    • Medium: describes the contact medium that could be used to contact the customer
      • City
      • Country
      • Email Address: Full email address in standard format
      • Type: Type of medium (fax, mobile phone…)
      • Number: Phone number
      • Postcode
      • State or province
      • Street 1: Describes the street
      • Street 2: Complementary street description
  • Disability: indicate lack or inadequate strength or ability
  • External Reference: to manage touch points to external OTT identifiers for the person (facebook, google+, …).
    • HREF: External reference
    • Type: Reference type
  • Individual Identification: represents our registration of information used as proof of identity by an individual (passport, national identity card, driver’s license, social security number, birth certificate)
    • Identification ID: identifier
    • Issuing Authority: Authority which has issued the identifier (social security, town hall…)
    • Issuing Date: Date at which the identifier was issued
    • Type: Identification type (passport, national identity card, driver’s license, social security number, birth certificate)
    • Other Name: To keep track of other names (for example the old name of a woman before marriage or an artist name)
    • Title: Useful for titles (aristocratic, social, …): Pr, Dr, Sir,…
    • Given Name: First name
    • Family Name: Last name
    • Middle Name
    • Full Name: Full name flatten (first, middle, and last names)
    • Formatted Name: A formatted name useful for specific contexts (Chinese, Japanese, Korean, …)
    • Valid For: The period for which the other name is valid
  • Related Party: Defines party or Party Role linked to a specific entity.
    • ID: Unique identifier of related party
    • Role: Role of the related party
    • Name: Name of the related party
    • Valid For: The period for which the related party is valid


Party individual UML model


Organization: represents a group of people identified by shared interests or purpose. Because of the complex nature of many businesses, both organizations and organization units are represented by the same business entity in this model.

  • Exists During: Details the establishment of the organization and its cessation
  • ID: Unique identifier for the organization
  • Is Legal Entity: To tag if the organization is a legal entity known by national referential
  • Name Type: “Co.”, “Inc.”, “Ltd.”, “Pty Ltd.” , “Plc.”, “Gmbh”
  • Status: Status of the organization - Initialized, Validated, Closed
  • Trading Name: The name that the organization (unit) trades under
  • Type: Type of Organization (Company, …)
  • Characteristic: describes the characteristics of the individual such as individual hobbies, center of interests.
    • Name: Name of the characteristic
    • Value: Value of the characteristic
    • Contact Medium: indicates the contact medium that could be used to contact the customer.
    • Preferred: If true, indicates that is the preferred contact medium
    • Type: Email address, telephone number, postal address
    • Valid For: The time period that the contact medium is valid for
    • Medium: describes the contact medium that could be used to contact the customer
      • City
      • Country
      • Email Address: Full email address in standard format
      • Type: Type of medium (fax, mobile phone…)
      • Number: Phone number
      • Postcode
      • State or province
      • Street 1: Describes the street
      • Street 2: Complementary street description
  • External Reference: to manage touch points to external OTT identifiers for the person (facebook, google+, …).
    • HREF: External reference
    • Type: Reference type
  • Organization Identification: represents our registration of information used as proof of identity by an organization
    • Identification ID: The name that the organization trades under
    • Issuing Authority: Authority which has issued the identifier (chamber of commerce…)
    • Issuing Date: Date at which the identifier was issued
    • Type: Type of identification information used to identify the company in a country or internationally
    • Valid For: The period for which the identification information is valid
  • Organization Child Relationship: represents the links between organizations: useful to describe an organization structure between headquarters, affiliates,…It indicates the children of the organization.
    • ID: Unique identifier of the child organization
    • Relationship Type: Juridical, hierarchical, geographical, functional…
    • Valid For: The time period the relationship is valid
  • Organization Parent Relationship: represents the links between organizations: useful to describe an organization structure between headquarters, affiliates,…It indicates the parent of the organization.
    • ID: Unique identifier of the parent organization
    • Relationship Type: Juridical, hierarchical, geographical, functional…
    • Valid For: The time period the relationship is valid
  • Other Name: To keep track of other names (for example the old name of a woman before marriage or an artist name)
    • Name Type: Co., Inc., Ltd., Pty Ltd. , Plc., Gmbh
    • Trading Name: The name that the organization trades under
    • Valid For: The period for which the other name is valid
  • Related Party: Defines party or Party Role linked to a specific entity.
    • ID: Unique identifier of related party
    • Role: Role of the related party
    • Name: Name of the related party
    • Valid For: The period for which the related party is valid


Party organization UML model

Customer Management API

Customer: A person or organization that buys products and services from the enterprise or receives free offers or services. This is modeled as a Party playing the role of Customer. A Customer is a type of Party Role.

  • Customer Rank: Relative importance of this customer compared to other customers
  • Description: Detailed description of the customer
  • ID: Unique identifier of the customer
  • Name: Displayable name
  • Status: Used to track the lifecycle status, e.g. existing, prospective or former customers
  • Valid For: To manage startDate and endDate of customer states
  • Characteristic: describes the characteristics of the individual or the organization such as individual hobbies, center of interests.
    • Name: Name of the characteristic
    • Value: Value of the characteristic
  • Contact Medium: indicates the contact medium that could be used to contact the customer.
    • Preferred: If true, indicates that is the preferred contact medium
    • Type: Email address, telephone number, postal address
    • Valid For: The time period that the contact medium is valid for
    • Medium: describes the contact medium that could be used to contact the customer
      • City
      • Country
      • Email Address: Full email address in standard format
      • Type: Type of medium (fax, mobile phone…)
      • Number: Phone number
      • Postcode
      • State Or Province
      • Street 1: Describes the street
      • Street 2: Complementary street description
  • Customer Account: Is used to represent an account for the customer to manage the billing aspects.
    • Description: Detailed description of the customer account
    • ID: Unique identifier of the customer account
    • Name: Name of the customer account
    • Status: The condition of the account, such as due, paid, in arrears, in collection
  • Customer Credit Profile: Credit profile for the customer (containing credit scoring, …). By default only the current credit profile is retrieved. It can be used as a list to give the customer credit profiles history, the first one in the list will be the current one.
    • Credit Profile Date: The date the profile was established.
    • Credit Risk Rating: This is an integer whose value is used to rate the risk
    • Credit Score: A measure of a person’s or organization’s creditworthiness calculated on the basis of a combination of factors such as their income and credit history.
    • Valid For: The period for which the profile is valid.
  • Payment Mean: defines a specific mean of payment (e.g. direct debit with all details associated).
    • ID: Unique identifier of the payment mean
    • Name: Name of the payment mean
  • Related Party: Defines party or partyRole linked to a specific entity.
    • ID: Unique identifier of related party
    • Role: Role of the related party
    • Name: Name of the related party
Customer UML Model


Customer Account: used to represent an account for the customer to manage billing aspects. Customer account can contain customer tax exemption, related accounts, contact information, customer relation, account balances and payment plans.

  • Account Type: A categorization of an account, such as individual, joint, and so forth, whose instances share some of the same characteristics.
  • Credit Limit: The maximum amount of money that may be charged on an account.
  • Description: Detailed description of the customer account
  • ID: Unique identifier of the customer account
  • Last Modified: Date of last modification of customer account
  • Name: Name of the customer account
  • PIN: A multidigit personal identification number that is used
  • Receivable Balance: Overall receivable balance for the customer account
  • Status: The condition of the account, such as due, paid, in arrears, in collection
  • Contact: An individual or an organization used as a contact point for a Customer Account and accessed via some contact medium.
    • Contact Type: Type of contact: Primary, secondary…
    • Valid For: Validity period of that contact
    • Contact Name: A displayable name for the contact
    • Party Role Type: Identifies what kind of Party Role type is linked to the contact (for instance customer account manager)
    • Related Party: Defines party or partyRole linked to a specific entity.
      • ID: Unique identifier of related party
      • Role: Role of the related party
      • Name: Name of the related party
      • Valid For: The period for which the related party is valid
    • Contact Medium: indicates the contact medium that could be used to contact the customer.
      • Preferred: If true, indicates that is the preferred contact medium
      • Type: Email address, telephone number, postal address
      • Valid For: The time period that the contact medium is valid for
      • Medium: describes the contact medium that could be used to contact the customer
        • City
        • Country
        • Email Address: Full email address in standard format
        • Type: Type of medium (fax, mobile phone…)
        • Number: Phone number
        • Postcode
        • State Or Province
        • Street 1: Describes the street
        • Street 2: Complementary street description
  • Customer: A person or organization that buys products and services from the enterprise or receives free offers or services. This is modeled as a Party playing the role of Customer. A Customer is a type of Party Role.
    • Customer Rank: Relative importance of this customer compared to other customers
    • Description: Detailed description of the customer
    • ID: Unique identifier of the customer
    • Name: Displayable name
    • Status: Used to track the lifecycle status, e.g. existing, prospective or former customers
    • Valid For: To manage startDate and endDate of customer states
  • Customer Account Relationship: Significant connection between customer accounts
    • Relationship Type: Type of relationship
    • Valid For: Validity period of that relationship
  • Customer Account Tax Exemption: Proof of freedom from taxes imposed by a taxing jurisdiction.
    • Certificate Number: Identifier of a document that shows proof of exemption from taxes for the taxing jurisdiction
    • Issuing Jurisdiction: Name of the taxing jurisdiction for which taxes are exempt.
    • Reason: Reason of the tax exemption
    • Valid For: Period for which the exemption is valid
  • Payment Plan: Defines a plan for payment (when a customer wants to spread his payments)
    • Amount: Amount paid.
    • Number Of Payments: Number of payments used to spread the global payment.
    • Payment Frequency: Monthly, Bimonthly, …
    • Priority: Priority of the payment plan
    • Status: Status of the payment plan (effective, ineffective).
    • Type: Type of payment plan
    • Valid For: Validity period of the payment plan.
    • Payment Mean: defines a specific mean of payment (e.g. direct debit with all details associated).
      • ID: Unique identifier of the payment mean
      • Name: Name of the payment mean
  • Customer Account Balance: Balances linked to the customer account.
    • Amount: Balance amount
    • Status: Due, Paid, …
    • Type: Deposit balance, Disputed balance, Loyalty balance, Receivable balance
    • Valid For: Balance validity period


Customer Account UML Model

Billing Management API

Billing Account: A detailed description of a customer’s bill structure.

  • ID: Unique identifier of the billing account
  • Name: A short descriptive name
  • Rating Type: Rating type (prepaid, postpaid) of the billing account
  • State: Used to track the lifecycle state
  • Valid For: The period for which the billing account is valid
  • Billing Account Balance: Balance of the Billing Account.
    • Type: Type of the balance
    • Amount: Balance amount
    • Valid For: Balance validity period
    • Status: Balance status
  • Customer Account: An arrangement that a customer has with an enterprise that provides products to the customer.
    • ID: unique identifier of the customer account
    • Name: A short descriptive name
  • Customer Billing Cycle Specification: A detailed description of when to initiate a billing cycle and the various sub steps of a billing cycle.
    • ID: Unique identifier of the customer billing cycle specification
    • Billing Date Shift: An offset of a billing date. The offset is expressed as number of days with regard to the start of the billing period.
    • Frequency: Frequency of the billing cycle (monthly for instance)
    • Name: A short descriptive name
  • Customer Bill Format: A detailed description of the way in which a customer’s bill is presented.
    • ID: Unique identifier of the customer bill presentation media
    • Name: A short descriptive name
  • Currency: A base / value business entity used to represent currency.
    • Currency Code: A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
  • Payment Mean: defines a specific mean of payment (e.g. direct debit with all details associated).
    • ID: Unique identifier of the payment mean
    • Name: Name of the payment mean
  • Related Party: Defines party or partyRole linked to a specific entity.
    • ID: Unique identifier of related party
    • Role: Role of the related party
Billing Account UML Model

The lifecycle of the Billing Account is described in the following diagram:

  1. Defined / created: billing account has been created but no related invoice can be produced
  2. Active: The billing account is active and related invoices are produced
  3. Pending update : billing account update is planned and will be effective for next billing cycle
  4. Suspended : billing account has been suspended on customer request or for other reasons (bad debts, etc.)
  5. Pending closed: the billing account will be closed when the last invoice will have been produced
  6. Closed : the billing account is closed and can not be changed to another state.


Billing Account Lifecycle

Applied Customer Billing Charge: An amount, usually of money, for which a person or an organization is financially liable.

  • ID: Unique identifier of the applied customer billing charge
  • Date: Creation date of the applied customer billing charge
  • Description: Additional data to be displayed on the customer bill for this applied customer billing charge
  • Type: Type of the applied customer billing charge (recurring, one time or usage) necessary to find the category of the invoice where the charge has to be displayed
  • Currency Code: A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
  • Tax Included Amount: All taxes included amount to be charged on the customer bill (expressed in the given currency)
  • Tax Excluded Amount: Tax excluded amount to be charged on the customer bill (expressed in the given currency)
  • Applied Customer Billing Tax Rate: An amount of money levied on the price of a product by a legislative body.
    • Amount: Tax amount
    • Tax Category: A categorization of the tax rate
  • Period: defines the period of a recurring charge
    • Start Period: Start date of the period
    • End Period: End date of the period
  • Product Specification: A detailed description of a tangible or intangible object made available externally in the form of a Product Offering to Customers or other Parties playing a PartyRole.
    • Product Number: An identification number assigned to uniquely identity the specification
    • Name: The name of the product specification
  • Service ID: defines the identifier of the service
    • ID: Identifier of the service
    • Type: Type of the service identifier (e.g. mobile number)
Applied Customer Billing Charge UML Model

Settlement Note Advice: The settlement is about transferring money receiving by a CSP to a partner. The settlement is notified to the partner with a settlement note advice containing details in settlement lines.

  • ID: A unique identifier for the settlement note advice
  • Date: Creation date of the settlement note advice
  • Description: A free description text
  • Payment Due Date: Date at which the due amount should have been paid to the partner
  • Tax Date: Date of the tax
  • Currency Code: A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
  • Tax Excluded Amount: All taxes excluded amount (expressed in the given currency)
  • Tax Included Amount: All taxes included amount (expressed in the given currency)
  • Tax Item: A tax item is created for each tax rate and tax type used in the settlement note.
    • Tax Category: Tax category (for example VAT)
    • Tax Rate
    • Tax Amount
  • Settlement Method: is the way in which the CSP provides the payment.
    • Code: Code of the settlement method
    • Label: A word, term or phrase by which a settlement method is known and distinguished from other settlement method
  • Receiver: Party Role who will receive the settlement note.
    • ID: Identifier of the receiver
  • Issuer: Party Role who will issue the settlement note.
    • ID: Identifier of the issuer
  • Tax Registration: The CSP and the partner could be registered with a tax number in a tax registration system.
    • Number: Tax registration number
  • Settlement Note Image: is the image of the settlement note.
    • Image Format: The format of the settlement note image (Csv, pdf, xls, txt…)
    • Image Size: The size of the settlement note image (in bytes)
    • Image File Name: The name of the file in which the settlement note image is saved
    • Image File URL: The URL of the settlement note image
  • Settlement Note Item: concerns a product identified by its catalogue reference. It could also follow a period delimited by a start and an end date.
    • Item Number: Unique number assigned to the settlement note item
    • Item Id: Unique identifier of the settlement note item
    • Item Label: A free description text for the settlement note item
    • Quantity: Quantity
    • Tax Excluded Unit Price: Tax excluded unit price to be applied on the given quantity
    • Tax Excluded Amount: Tax excluded amount equal to quantity * Tax Excluded Unit Price
    • Tax Included Amount: All taxes included amount equal to Tax Excluded Amount + Tax Amount
    • Period: defines the period of a recurring charge
      • Start Period: Start date of the period
      • End Period: End date of the period
    • Product Specification: A detailed description of a tangible or intangible object made available externally in the form of a Product Offering to Customers or other Parties playing a PartyRole.
      • Product Number: An identification number assigned to uniquely identity the specification
      • Name: The name of the product specification
Applied Customer Billing Charge UML Model

Catalog Management API

Catalog: A Product Catalog is a collection of Product Offerings, intended for a specific DistributionChannel, enhanced with additional information such as SLA parameters, invoicing and shipping details. Each Product Offering in a Product Catalog combines pricing and availability information with Product Specifications that describe the relationships between Products, the Services used to realize the Products, and the Resources they require.

  • Name: name of the catalog.
  • Version: Catalog version.
  • Last Update: Date and time of the last update.
  • Type: Indicates if the catalog is a product, service or resource catalog.
  • Category: is used to group product offerings, service and resource candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.
  • Related Party: Defines party or partyRole linked to a specific entity.
  • LifeCycle Status: Used to indicate the current lifecycle status.
  • Valid For: The period for which the catalog is valid.


Catalog UML model

Category: The category resource is used to group product offerings, service and resource candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.

  • Description: Description of the category.
  • ID: Unique identifier of the category.
  • Is Root: If true, this Boolean indicates that the category is a root of categories.
  • Last Update: Date and time of the last update.
  • LifeCycle Status: Used to indicate the current lifecycle status.
  • Name: Name of the category.
  • Parent Id: Unique identifier of the parent category.
  • Valid For: The period for which the category is valid.
  • Version: Category version.


Category UML model

Product Offering: The Product Offering resource represents entities that are orderable from the provider of the catalog, this resource includes pricing information.

  • Description: Description of the Product Offering
  • ID: Unique identifier of the Product Offering
  • Is Bundle: determines whether a Product Offering represents a single Product Offering (false), or a bundle of Product Offerings (true).
  • Last Update: Date and time of the last update
  • Lifecycle Status: Used to indicate the current lifecycle status
  • Name: Name of the product Offering
  • Valid For: The period for which the product Offering is valid
  • Version: Product Offering version
  • Bundled Product Offering: A type of Product Offering that belongs to a grouping of Product Offerings made available to the market. It inherits of all attributes of Product Offering.
  • Category: is used to group product offerings, service and resource candidates in logical containers. Categories can contain other categories and/or product offerings, resource or service candidates.
  • Channel: Defines the channel for selling product offerings.
  • Place: Defines the places where the product offerings are sold.
  • Product Offering Price: Is based on both the basic cost to develop and produce products and the enterprise’s policy on revenue targets. This price may be further revised through discounting (prodOfferPriceAlteration). The price, applied for a Product Offering may also be influenced by the Product Offering Term, the customer selected – e.g. a Product Offering can be offered with multiple terms, like commitment periods for the contract. The price may be influenced by this Product Offering Term. A Product Offering may be cheaper with a 24 month commitment than with a 12 month commitment.
    • Description: Description of the Product Offering Price
    • Name: Name of the Product Offering Price
    • Price Type: Indicates the price type: recurring, one time, usage
    • Recurring Charge Period: Could be month, week…
    • Unit Of Measure: Could be minutes, GB…
    • Valid For: The period for which the Product Offering Price is valid
    • Version: Product Offering Price version
    • Price: Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for ProdOfferPriceAlteration.
      • Currency Code: A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
      • Duty Free Amount: All taxes excluded amount (expressed in the given currency)
      • Percentage: Percentage to apply for Product Offer Price Alteration.
      • Tax Included Amount: All taxes included amount (expressed in the given currency)
      • Price Type: Indicates the price type: recurring, one time, usage
      • Tax Rate: Tax rate
    • Product Offer Price Alteration: An amount, usually of money, that modifies a price charged for a Product Offering.
    • Application Duration: Duration during which the Product Offer Price Alteration applies on the Product Offering (for instance 2 months free of charge for the recurring charge)
      • Description: Description of the Product Offer Price Alteration
      • ID: Unique identifier of the Product Offer Price Alteration
      • Name: Name of the Product Offer Price Alteration
      • Price Condition: Condition that triggers the price application
      • Price Type: Indicates the price type: recurring, one time, usage
      • Recurring Charge Period: Could be month, week…
      • Unit Of Measure: Could be minutes, GB…
      • Valid For: The period for which the Product Offer Price Alteration is valid
  • Product Offering Term: A condition under which a Product Offering is made available to Customers. For instance, a Product Offering can be offered with multiple commitment periods.
    • Description: Description of the Product Offering Term
    • Duration: Duration of the Product Offering Term
    • Name: Name of the Product Offering Term
    • Valid For: The period for which the Product Offering Term is valid
  • Product Specification: A detailed description of a tangible or intangible object made available externally in the form of a Product Offering to customers or other parties playing a party role.
    • Brand: The manufacturer or trademark of the specification
    • Description: A narrative that explains in detail what the product specification is
    • ID: Unique identifier of the product specification
    • Is Bundle: determines whether a Product Specification represents a single Product Specification (false), or a bundle of Product Specification (true).
    • Last Update: Date and time of the last update
    • Lifecycle Status: Used to indicate the current lifecycle status
    • Name: Name of the product specification
    • Product Number: An identification number assigned to uniquely identify the specification
    • Valid For: The period for which the product specification is valid
    • Version: Product specification version
  • 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. One Service Specification can be composed of other Service Specifications. The Service Candidate consists of a subset of Service Specification characteristics to fulfill a product offering. These Service Specifications may also be published.
    • Description: A narrative that explains in detail what the service candidate is
    • ID: Unique identifier of the service candidate
    • Last Update: Date and time of the last update
    • Lifecycle Status: Used to indicate the current lifecycle status
    • Name: Name of the service candidate
    • Valid For: The period for which the service candidate is valid
    • Version: Service candidate version
  • Service Level Agreement: A service level agreement (SLA) is a type of agreement that represents a formal negotiated agreement between two parties designed to create a common understanding about products, services, priorities, responsibilities, and so forth. The SLA is a set of appropriate procedures and targets formally or informally agreed between parties in order to achieve and maintain specified Quality of Service.
  • Resource Candidate: Is an entity that makes a Resource Specification available to a catalog. A Resource Candidate and its associated Resource Specification may be published - made visible - in any number of Resource Catalogs, or in none. One Resource Specification can be composed of other Resource Specifications. The Resource Candidate consists of a subset of Resource Specification characteristics to fulfill a product offering. These Resource Specifications may also be published.
Product Offering UML model

Product Specification: The Product Specification Resource is a detailed description of a tangible or intangible object made available externally in the form of a Product Offering to customers or other parties playing a party role.

  • Brand: The manufacturer or trademark of the specification
  • Description: A narrative that explains in detail what the product specification is
  • ID: Unique identifier of the product specification
  • Is Bundle: determines whether a Product Specification represents a single Product Specification (false), or a bundle of Product Specification (true).
  • Last Update: Date and time of the last update
  • Lifecycle Status: Used to indicate the current lifecycle status
  • Name: Name of the product specification
  • Product Number: An identification number assigned to uniquely identify the specification
  • Valid For: The period for which the product specification is valid
  • Version: Product specification version
  • Attachment: describes a product through video, pictures…
    • ID: Unique identifier of the attachment
    • Type: Attachment type such as video, picture
    • URL: Uniform Resource Locator, is a web page address (a subset of URI)
  • Bundled Product Specification: A type of Product Specification that belongs to a grouping of Product Specifications made available to the market. It inherits of all attributes of Product Specification.
  • Product Spec Characteristic: A characteristic quality or distinctive feature of a Product Specification. The characteristic can be take on a discrete value, such as color, can take on a range of values, (for example, sensitivity of 100-240 mV), or can be derived from a formula (for example, usage time (hrs) = 30 – talk time *3). Certain characteristics, such as color, may be configured during the ordering or some other process.
    • Configurable: If true, the Boolean indicates that the Product Spec Characteristic is configurable
    • Description: A narrative that explains in detail what the Product Spec Characteristic is
    • Name: Name of the Product Spec Characteristic
    • Value Type: A kind of value that the characteristic can take on, such as numeric, text and so forth
    • Valid For: The period for which the Product Spec Characteristic is valid
    • Product Spec Characteristic Value: A number or text that can be assigned to a Product Spec Characteristic.
      • Default: Indicates if the value is the default value for a characteristic
      • Unit Of Measure: Could be minutes, GB…
      • Valid For: The period of time for which a value is applicable
      • Value: A discrete value that the characteristic can take on
      • Value From: The low range value that a characteristic can take on
      • Value To: The upper range value that a characteristic can take on
      • Value Type: A kind of value that the characteristic can take on, such as numeric, text, and so forth
  • Product Specification Relationship: A migration, substitution, dependency or exclusivity relationship between/among product specifications.
    • Valid For: The period for which the Product Specification Relationship is valid
    • Type: Type of relationship such as migration, substitution, dependency, exclusivity
    • ID: Unique identifier of the Product Specification
  • Related Party: Defines party or Party Role linked to a specific entity.
    • ID: Unique identifier of related party
    • Name: Name of the related party
    • Role: Role of the related party
    • Valid For: The period for which the related party is linked to the entity
  • Resource Specification: Resource Specification(s) required to realize a Product Specification.
    • ID: Unique identifier of the resource specification
    • Name: Name of the required Resource Specification
    • Version: Resource specification version
  • Service Specification: Service Specification(s) required to realize a Product Specification.
    • ID: Unique identifier of the service specification
    • Name: Name of the required Service Specification
    • Version: Service specification version
Product Spec UML model

The diagram below represents the lifecycle of all the elements managed by the Product Catalog API (catalogs, categories, products, offerings, etc.).

  1. When the macro conception of a catalog element is started the first status of the later is In Study.
  2. When the conception of the catalog element is accepted its status is changed to In Design.
  3. If the design is approved its status is changed to In Test.
  4. Then either the test is OK and then its status is changed to Active or the test is KO and its status is changed to Rejected. The Rejected status is a final status.
  5. When a catalog element is in an Active status it means it has been validated and tested, but it is still not available for customers.
  6. When the beginning of marketing is reached, its status is changed to Launched. At this moment customers can buy it.
  7. If the catalog element is not launched, its status is changed to Retired.
  8. The same status is achieved when a catalog element reaches the end of marketing.
  9. The Retired status means it can not be sold to any new customers, but previous customers can still have it.
  10. When no more customer holds the catalog element, its status is changed to Obsolete meaning it can be removed from the catalog.
Catalog Element Lifecycle

Ordering Management API

Product Order is a type of order which can Be used to place an order between a customer and a service provider or between a service provider and a partner and vice versa.

  • Category: Used to categorize the order from a business perspective that can be useful for the OM system (e.g. “enterprise”, “residential”, ...)
  • Completion Date: Date when the order was completed
  • Description: Description of the product order
  • Expected Completion Date: Expected delivery date amended by the provider
  • External ID: ID given by the consumer and only understandable by him (to facilitate his searches afterwards)
  • ID: ID created on repository side (OM system)
  • Notification Contact: Contact attached to the order to send back information regarding this order
  • Order Date: Date when the order was created
  • Priority: A way that can be used by consumers to prioritize orders in OM system (from 0 to 4 : 0 is the highest priority, and 4 the lowest)
  • Requested Completion Date: Requested delivery date from the requestor perspective
  • Requested Start Date: Order start date wished by the requestor
  • State: State of the order. It can be:
    • Acknowledged: when an order has been received and has passed message and basic business validations.
    • In Progress: when an order has passed the Order Feasibility check successfully and service delivery has started.
    • Cancelled: when an In-Flight Order has been successfully cancelled.
    • Completed: when an order has complete provision and the service is now active.
    • Rejected:
      • An order failed the Order Feasibility check
      • Invalid information is provided through the order request
      • The order request fails to meet business rules for ordering.
    • Pending: when an order is currently in a waiting stage for an action/activity to be completed before the order can progress further, pending order amend or cancel assessment. In situations where Access Seeker action is required, an “information required” notification will be issued on transition into this state. A pending stage can lead into auto cancellation of an order, if no action is taken within the defined timeframes to be described under the Agreement.
    • Held: The Held state is used when an order cannot be progressed due to an issue. SP has temporarily delayed completing an order to resolve an infrastructure shortfall to facilitate supply of order. Upon resolution of the issue, the order will continue to progress.
    • Failed: All Order items have failed which results in the entire Order has Failed.
    • Partial: Some Order items have failed and some have succeeded so the entire Order is in a Partial state. This provides support for partial Failure of an Order
  • Billing Account: is the Billing Account to use to bill the ordered products
  • Note: Extra-information about the order (e.g. useful to add extra delivery information that could be useful for a human process : a digicode access to a building, …).
    • Date: Date of the note
    • Author: Author of the note
    • Text: Text of the note
  • Order Item: Order items that have to be treated
    • ID: Identifier of the line item (generally it is a sequence number 01, 02, 03, …)
    • Action: Can be “add” / “modify” / “no_change”/ “delete”
    • State: State of the order item. It takes the same value than the state of an ordering.
    • Appointment: Used to precise that an appointment was set up with a related party for this order item
  • Place: Used to defined a place useful for the product (for example a delivery geographical place)
    • Role: Role of the place (for instance delivery geographical place)
  • Product: Configure the product characteristics (only configurable characteristics and necessary only if a non-default value is selected) and/or identify the product that needs to be modified/deleted. May be a bundle product instantiation, in this case, it will contain the list of bundled product to instantiate. Each product to instantiate corresponds to a purchased Product Offering. In case of bundles, the order of the list in the Product Offering bundle must match the order of the list in the product instance bundle to deliver.
    • Product Characteristic: Characteristics of the product to instantiate or to modify
      • Name: Name of the characteristic
      • Value: Value of the characteristic
    • Product Relationship: Linked products to the one instantiate.
      • Type: Type of the product relationship. It can be :
        • bundled if the product is a bundle and you want to describe the “bundled” products inside this bundle
        • reliesOn if the product needs another already owned product to rely on (e.g. an option on an already owned mobile access product)
        • targets or isTargeted (depending on the way of expressing the link) for any other kind of links that may be useful
  • Product Offering: Ordered offering (pricing, default values, etc. are fetched by the OM directly from the catalogue). May be a bundle Product Offering, in this case, it will contain the list of bundled offers that are ordered
  • Related Party: Defines parties which are involved in the order and the role they are playing. At product order level, it may be the customer and at the product level, it may be the user.
    • ID: Unique identifier of related party
    • Role: Role of the related party
    • Name: Name of the related party
Ordering UML model

The diagram below represents the lifecycle that orderings will follow:

  1. The Acknowledged state is when an order has been received and has passed message and basic business validations.
  2. The In Progress state is when an order has passed the Order Feasibility check successfully and service delivery has started.
  3. The Cancelled state is when an In-Flight Order has been successfully cancelled.
  4. The Completed state is when an order has complete provision and the service is now active.
  5. The Rejected state is where:
    1. An order failed the Order Feasibility check
    2. Invalid information is provided through the order request
    3. The order request fails to meet business rules for ordering.
  6. The Pending state is used when an order is currently in a waiting stage for an action/activity to be completed before the order can progress further, pending order amend or cancel assessment. In situations where Access Seeker action is required, an “information required” notification will be issued on transition into this state. A pending stage can lead into auto cancellation of an order, if no action is taken within the defined timeframes to be described under the Agreement.
  7. The Held state is used when an order cannot be progressed due to an issue. SP has temporarily delayed completing an order to resolve an infrastructure shortfall to facilitate supply of order. Upon resolution of the issue, the order will continue to progress.
  8. The Failed state occurs when all Order items have failed which results in the entire Order has Failed.
  9. The Partial state is when Some Order items have failed and some have succeeded so the entire Order is in a Partial state. This provides support for partial Failure of an Order
Ordering Lifecycle

Inventory Management API

The product inventory API allows to register the Resource(s) a purchaser has acquired. The fields of these resources are:

  • ID: “is the ID created for the product
  • Name: is the name of the product. It could be the same as the name of the Product Offering
  • Description: is the description of the product. It could be copied from the description of the Product Offering.
  • Status: “status” is the lifecycle status of the product.
  • Is Bundle
  • Is Customer Visible
  • Product Serial Number: is the serial number for the product. This is typically applicable to tangible products e.g. Broadband Router.
  • Start Date: is the date from which the product starts
  • Order Date: is the date when the product was ordered.
  • Termination Date: is the date when the product was terminated. Not applicable to active products.
  • Product Offering: is a link to the product offering.
  • Product Specification: is a link to the product specification. It may be useful to manage links directly to the ProductSpec, when the product is a non-bundle one you may not manage the Product Offering link with this Product.
  • Product Characteristics: is a list of name value pairs to list the various relevant characteristics of the instantiated product.
  • Product Relationships: is a collection of a number of types of relationships between the product e.g bundle. The value of the ‘type’ attribute should describe the direction of the relationship. E.g. “isContainedIn”
  • Billing Account: is a link to the billing account on which the product is billed. This is optional because in some cases the parent is billed and not all the children.
  • Related Parties: is a link to collection of parties. Each party will contain a role and a link.
  • Agreement Item: is a link to the agreement item for the product. Agreement item will contain the terms and conditions for the product including the product term.
  • Place: is a link to the place where the product is provided.
  • Service: is a link to the service that realizes the product.
  • Resource: is a link to the resource that realizes the product.
  • Product Price: is a collection of all applicable prices for the product, it’s an override of the default one specified in the Product Offering.
Inventory Resource UML model

The lifecycle of these resource is represented below:

  1. Created: No identified status yet - newly injected into the target system
  2. Pending Active: Prepared, but not active for customer yet
  3. Aborted: Activation aborted for technical / internal reasons
  4. Cancelled: Activation aborted by customer / legal request
  5. Active: Active for customer use of product
  6. Pending Terminate: To be terminated, but still in use
  7. Terminated: No longer active for customer
  8. Suspended: Temporary suspension, not usable for customer, typically because of barring caused by payment / dunning issues or customer request
Inventory Lifecycle

Usage Management API

Usage: an occurrence of employing a Product, Service, or Resource for its intended purpose, which is of interest to the business and can have charges applied to it. It is comprised of characteristics, which represent attributes of usage.

  • Date: Date of usage
  • Description: Description of usage
  • ID: Usage unique identifier
  • Status: Status of usage
  • Type: Type of usage
  • Rated Product Usage: An occurrence of employing a product for its intended purpose with all rating details.
    • Bucket Value Converted In Amount: Monetary value of bucket
    • Currency Code: A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
    • Is Billed: Boolean indicating if usage have been billed or not
    • Is Tax Exempt: Indicates if the rated amount is exempt of tax
    • Offer Tariff Type: Type of tariff applied
    • Product Ref: Reference of product specification
    • Rating Amount Type: Type of amount
    • Rating Date: Date of usage rating
    • Tax Excluded Rating Amount: All taxes excluded rated amount
    • Tax Included Rating Amount: All taxes included rated amount
    • Tax Rate
    • Usage Rating Tag: Tag value:
      • usage: the usage is always rated outside a usage bundle
      • included usage: the usage is rated inside a usage bundle
      • non included usage: the usage bundle is exhausted. The usage is rated outside the usage bundle
  • Related Party: Defines party or partyRole linked to a specific entity.
    • ID: Unique identifier of the related party
    • Name: Name of the related party
    • Role: Role of the related party
    • Valid For: The period for which the related party is linked to the entity
  • Usage Characteristic: Provides the value of a given characteristic.
    • Name: The name of the usage characteristic.
    • Value: A discrete value that the characteristic can take on.
  • Usage Specification: A detailed description of a usage event that are of interest to the business and can have charges applied to it. It is comprised of characteristics, which define all attributes known for a particular type of usage.
    • Description: A narrative that explains in detail what the usage specification is
    • ID: Usage specification unique identifier
    • Name: The name of the usage specification.
    • Valid For: The period for which the usage specification is valid
  • Usage Spec Characteristic: A detailed description of an attribute that defines a particular type of usage, described by its name, category, type, presence and a set of allowed values
    • Configurable: Boolean indicating if Usage Spec Characteristic is configurable or not
    • Description: A narrative that explains in detail what the usage specification characteristic is
    • Name: The name of the usage specification characteristic
    • Usage Spec Characteristic Value: A value that can be assigned to a UsageSpecCharacteristic.
      • Default: Indicates if the value is the default value for a characteristic
      • Value: A narrative that explains in detail what the usage specification characteristic is
      • Value Type: A kind of value that the characteristic can take on, such as numeric, text, and so forth.
      • Value From: The low range value that a characteristic can take on.
      • Value To: The upper range value that a characteristic can take on.
Usage UML model

The following diagrams represents the lifecycle of the usage resource:

  1. Received: Newly injected into the target system
  2. Rejected: Rejected for validation error or similar reasons
  3. Recycled: Resubmitted after error correction
  4. Guided: Identified with customer and product references
  5. Rated: From this status on, the ratedProductUsage collection will have a value
  6. Rerate: Marked for re-rating
  7. Billed: Billed for customer invoice
Usage Lifecycle

Example Scenarios

This section describes the operation of the Business API Ecosystem GE from the viewpoint of users, without taking into account the interactions between different components. To do this, we propose some specific use cases that refer to prospective real interactions of Business API Ecosystem GE users from both the web portal and other Generic Enablers that use the Business API Ecosystem GE RESTful APIs.

Creating and publishing offerings

This use cases describe the process that service sellers would complete when they decide to put a new service up for sale in the Business API Ecosystem GE. To illustrate how the Business API Ecosystem GE can be combined with other FIWARE GEs, we will define a use case where the user playing the Seller role has created a new dataset in the Open Data GE (aka CKAN). In this case, the offering to be published will give the consumer the required rights to access the dataset published by the seller.

So, the first step is to create the dataset in the Open Data portal and mark it as private. The user will then access the Business API Ecosystem GE and will create a product describing the dataset (its location, type, etc.). After that, the seller will create an offering that contains the created product. The offering will contain the commercial information of the dataset, such as the pricing. It is important to note that the offering will not be available to prospective customer until it is launched. For this reason, the last step is to launch the offering. To do so, the seller will access the offering and will change its state to Launched.

Searching and purchasing offerings

This use case describes the process that a user playing the Customer role would enact as of when he or she searches offerings via the web portal provided by the Business API Ecosystem GE to when he or she purchases an offering. In this use case, the user is assumed to be using the Business API Ecosystem GE web portal to purchase an offering that requires an initial payment.

First the user will login to the FIWARE platform. This will identify the user within the Business API Ecosystem GE. The logged user will access the Business API Ecosystem GE web portal and select the advanced search option. This way, he or she will be able to filter the search by the type of products associated with the offering. The search will return a series of offerings that meet the requested parameters, and the user will select the one that best satisfies his or her needs and preferences. When the user has decided which offering to purchase, he or she will select the option to purchase the offering. The Business API Ecosystem GE will then request the information necessary to make the payment (account number, card number, PayPal account, etc.). After payment confirmation, the Business API Ecosystem GE will download the transaction invoice and reroute the user to the service provider to get access credentials from the provider. When this process is completed, this offering and its associated resources will be part of the offerings owned by the user and he or she will be able to download the invoice and get access credentials.

Main Interactions

Creating a Catalog

The figure below shows the interactions that take place to create and launch a new catalog in the Business API Ecosystem

Creating a catalog


In the diagram above it can be seen the basic functionality provided in order to create a catalog. In this case, a user with the seller role provides all the needed catalog information as described in Data Model section (using the protal or the REST API) and makes the createCatalog request to the APIs Orchestrator, this component validates the catalog information and redirects the request to the Catalog Management API. As a result the information of the new catalog is returned to the seller user.

Once the catalog has been created, the user has to change its state to launched in order to make the catalog available to product offering sellers.

Creating a Product Offering

The figure below shows the basic interactions required for creating a product offering

Creating a product offering


It can be seen that the creation of a product offering has two main phases. On the one hand, the seller has to register a new product specification. To do that, she has to provide the information of the product spec to the APIs Orchestrator by using the createProduct request. Then the APIs Orchestrator validates the information with the Charging Management module, since this module is the one that activates the service and thus the one that is able to check the concrete characteristics of the concrete product spec. Finally, the APIs Orchestrator redirects the creation request to the Catalog Management API.

On the other hand, the seller has to create the product offering, specifing the concrete product to be sold and the catalog where the offering is going to be published. Then, the APIs Orchestrator validates the product offering with the Charging Management module, which is the component able to check the included pricing models and currencies. Finally, the APIs Orchestrator redirects the creation request to the Catalog Mangement API.

It is important to remark that to start selling the product offering it is required to launch it. To do that, the first step is launching the product specification as can be seen in the diagram above, and then launching the product offering in a similar way.

Retiring a Product Offering

The figure below shows the interactions that take place to retire a product offering in the Business API Ecosystem.

Retiring a product offering


In the diagram above it can be seen the basic functionality provided in order to retire an offering. In this case, a user with the seller role makes the retireOffering request to the APIs Orchestrator. This component validates that the user is allowed to perform this request and redirects the request to the Catalog Management API. As a result, the updated information of the offering is returned.

Once the offering is retired, customers will not be able to purchase it.

Creating an Ordering

The figure below shows the interactions that take place to create an ordering in the Business API Ecosystem.

Creating an Ordering

Prior to creating an ordering, the user should have chosen the items to be ordered. The API Orchestrator provides a functionality called Shopping Cart to store all the items that will be included in an ordering. To simplify, this process has not been included in the diagram above.

The process of creating an ordering will be eased by the usage of the web portal that guides the user through the different steps. The first step is to confirm the ordering. Then, the ordering is sent to the API Orchestrator that will validate that all the contained information (product and offering) is valid by retrieving the required data from the Catalog Management API. Once the information has been validated, the ordering is created by redirecting the request to the Ordering Management API. Orderings are created in a special state so sellers will not be able to modify them until the payment process is completed.

To complete the payment, the API Orchestrator contacts the Charging Management that will start the payment by accessing the Payment Platform. Then, the Payment Platform will return a redirection URL that should be proxied to the Web Portal so the user can accept the payment. In that way, the Web Portal will redirect the user to the Payment Platform and they will accept the payment. Finally, the Payment Platform will redirect the user to the Web Portal which will access the Charging Management again to finish the payment. When the payment is completed, the ordering will be activated and sellers will be able to manage it.

The way the items contained in an ordering are delivered depends on its type: Physical or Digital.

Delivering Digital Items

The Business API Ecosystem GE is intended for granting access to digital services automatically. To do so, when an ordering is created, the Charging Management will activate all the digital items contained in the ordering by accessing the Ordering Management API. When a product is activated, it is automatically registered in the user's inventory making usage of the Inventory Management API. The Charging Management is subscribed to the Inventory Management API so every time a product is added, it gets notified. In this way, when the Charing Management receives a notification involving a digital product, it tries to activate the service for the customer that acquired it. From that moment, the customer will be able to access the service.

Activating Digital Products

Delivering Physical Items

Delivering Physical products is a little bit different as sellers are the only ones in charge of sending it. For this reason, the first step sellers take is to retrieve the list of pending orderings. This request is sent to the API Orchestrator that will proxy it to the Ordering Management API. Once sellers have retrieved the list of pending orderings, they will select one and start with the physical delivery. In case a physical address is needed, sellers can take advantage of both the Billing Management API and the Customer Management API. Then, when the product has been delivered to the customer, sellers must activate it by accessing the Ordering Management API through the API Orchestrator. This will add the product to the customer's inventory and the Charging Management will activate the inventory product thanks to the existing subscription.

Activating Physical Products

Managing Usage-based Models

The following diagrams show the basic interactions regarding the management of usage-based models. Concretely, the first diagram shows the interactions for feeding accounting information, the second shows the process for suspending a service with a pending payment, and the last one shows the process of paying for a service with a usage-based model. Note that all this interaction diagrams suppose that the concrete product has been acquired following the process described in the section Create an Ordering.

File:Feed-accounting-dg.png
Feed accounting data

The diagram above shows the process of feeding accounting information. It can be seen that the accounting information is generated by the Accounting Proxy which is monitoring the concrete service. This proxy sends this accounting data, created in the format specified in Data Model section, to the Usage Management API which will store the information and make it available to the rest of the ecosystem.


File:Suspend-product-dg.png
Suspend service

The previous diagram shows the process of suspending a product. Prior to this process, the Accounting Proxy had been feeding the ecosystem with usage information. Periodically, this usage information has to be rated and charged. Therefore, when the usage period ends, the service is suspended until the customer pays her pending usage.

It can be seen, that the Charging Management module suspends the product in the Inventory Management API, and then it suspends the offered service. Finally, the Charging Management module notifies the customer that one of her acquired products has been suspended.


Resolve usage charge

Finally, the diagram above shows the process of paying for the usage made of a service during a usage period. It is shown that the customer has to make a renovateProduct request to the APIs Orchestrator which authenticates the user and redirects the request to the Charging Management module. This module retrieves the product information from the Inventory Management API and the usage made from the Usage Management API. Then, it calculates the amount to be paid by the customer and executes the payment in the Payment Platform (Note that the payment process has been simplified in this diagram, the complete process is explained in the Create Ordering section).

Once the payment confirmation has been received, the Charging Management module updates the usage information in the Usage Management API with the rated usage. Finally, it activates the concrete service and the product in the Inventory Management API in a similar way as the explained in the section Create an Ordering.

Basic Design Principles

  • API Technology Independence
The API abstracts from the specific implementation technology. Implementations using more than one type of platform and framework should be possible.
  • Web Browsers should not limit the functionalities of the Business API Ecosystem GE
HTML5, CSS and JavaScript must be used to fully exploit the brand new Web applications capabilities.


Detailed Specifications

The Business API Ecosystem GE exposes its functionality though a REST API. The Open API Specification for this GE can be found in the following link:

Re-utilised Technologies/Specifications

The Business API Ecosystem GE is based on the REST API Specifications provided by the TM Forum as part of its API business ecosystem. The following specifications have been used for the design of the GE:

  • Product Catalog Management API
  • Product Ordering Management API
  • Product Inventory Management API
  • Party Management API
  • Customer Management API
  • Billing Management API
  • Usage Management API

The TM Forum specifications can be found in the following link:

Terms and definitions

This section comprises a summary of terms and definitions introduced during the previous sections. It intends to establish a vocabulary that will be of help to carry out discussions internally and with third parties (e.g., Use Case projects in the EU FP7 Future Internet PPP). For a summary of terms and definitions managed at overall FIWARE level, please refer to FIWARE Global Terms and Definitions

  • Aggregator (Role): A Role that supports domain specialists and third-parties in aggregating services and apps for new and unforeseen opportunities and needs. It does so by providing the dedicated tooling for aggregating services at different levels: UI, service operation, business process or business object levels.
  • Application: Applications in FIWARE are composite services that have a IT supported interaction interface (user interface). In most cases consumers do not buy the application, instead they buy the right to use the application (user license).
  • Broker (Role): The business network’s central point of service access, being used to expose services from providers that are delivered through the Broker’s service delivery functionality. The broker is the central instance for enabling monetization.
  • Business Element: Core element of a business model, such as pricing models, revenue sharing models, promotions, SLAs, etc.
  • Business Framework: Set of concepts and assets responsible for supporting the implementation of innovative business models in a flexible way.
  • Business Model: Strategy and approach that defines how a particular service/application is supposed to generate revenue and profit. Therefore, a Business Model can be implemented as a set of business elements which can be combined and customized in a flexible way and in accordance to business and market requirements and other characteristics.
  • Business Process: Set of related and structured activities producing a specific service or product, thereby achieving one or more business objectives. An operational business process clearly defines the roles and tasks of all involved parties inside an organization to achieve one specific goal.
  • Business Role: Set of responsibilities and tasks that can be assigned to concrete business role owners, such as a human being or a software component.
  • Channel: Resources through which services are accessed by end users. Examples for well-known channels are Web sites/portals, web-based brokers (like iTunes, eBay and Amazon), social networks (like Facebook, LinkedIn and MySpace), mobile channels (Android, iOS) and work centers. The access mode to these channels is governed by technical channels like the Web, mobile devices and voice response, where each of these channels requires its own specific workflow.
  • Channel Maker (Role): Supports parties in creating outlets (the Channels) through which services are consumed, i.e. Web sites, social networks or mobile platforms. The Channel Maker interacts with the Broker for discovery of services during the process of creating or updating channel specifications as well as for storing channel specifications and channeled service constraints in the Broker.
  • Composite Service (composition): Executable composition of business back-end MACs (see MAC definition later in this list). Common composite services are either orchestrated or choreographed. Orchestrated compositions are defined by a centralized control flow managed by a unique process that orchestrates all the interactions (according to the control flow) between the external services that participate in the composition. Choreographed compositions do not have a centralized process, thus the services participating in the composition autonomously coordinate each other according to some specified coordination rules. Backend compositions are executed in dedicated process execution engines. Target users of tools for creating Composites Services are technical users with algorithmic and process management skills.
  • Consumer (Role): Actor who searches for and consumes particular business functionality exposed on the Web as a service/application that satisfies her own needs.
  • Desktop Environment: Multi-channel client platform enabling users to access and use their applications and services.
  • Front-end/Back-end Composition: Front-end compositions define a front-end application as an aggregation of visual mashable application pieces (named as widgets, gadgets, portlets, etc.) and back-end services. Front-end compositions interact with end-users, in the sense that front-end compositions consume data provided by the end-users and provide data to them. Thus the front-end composition (or mashup) will have a direct influence on the application look and feel; every component will add a new user interaction feature. Back-end compositions define a back-end business service (also known as process) as an aggregation of backend services as defined for service composition term, the end-user being oblivious to the composition process. While back-end components represent atomization of business logic and information processing, front-end components represent atomization of information presentation and user interaction.
  • Gateway (Role): The Gateway role enables linking between separate systems and services, allowing them to exchange information in a controlled way despite different technologies and authoritative realms. A Gateway provides interoperability solutions for other applications, including data mapping as well as run-time data store-forward and message translation. Gateway services are advertised through the Broker, allowing providers and aggregators to search for candidate gateway services for interface adaptation to particular message standards. The Mediation is the central generic enabler. Other important functionalities are eventing, dispatching, security, connectors and integration adaptors, configuration, and change propagation.
  • Hoster (Role): Allows the various infrastructure services in cloud environments to be leveraged as part of provisioning an application in a business network. A service can be deployed onto a specific cloud using the Hoster’s interface. This enables service providers to re-host services and applications from their on-premise environments to cloud-based, on-demand environments to attract new users at much lower cost.
  • Marketplace: Part of the business framework providing means for service providers, to publish their service offerings, and means for service consumers, to compare and select a specific service implementation. A marketplace can offer services from different stores and thus different service providers. The actual buying of a specific service is handled by the related service store.
  • Mashup: Executable composition of front-end MACs. There are several kinds of mashups, depending on the technique of composition (spatial rearrangement, wiring, piping, etc.) and the MACs used. They are called application mashups when applications are composed to build new applications and services/data mash-ups if services are composed to generate new services. While composite service is a common term in backend services implementing business processes, the term ‘mashup’ is widely adopted when referring to Web resources (data, services and applications). Front-end compositions heavily depend on the available device environment (including the chosen presentation channels). Target users of mashup platforms are typically users without technical or programming expertise.
  • Mashable Application Component (MAC): Functional entity able to be consumed executed or combined. Usually this applies to components that will offer not only their main behaviour but also the necessary functionality to allow further compositions with other components. It is envisioned that MACs will offer access, through applications and/or services, to any available FIWARE resource or functionality, including gadgets, services, data sources, content, and things. Alternatively, it can be denoted as ‘service component’ or ‘application component’.
  • Monetization: Process or activity to provide a product (in this context: a service) in exchange for money. The Provider publishes certain functionality and makes it available through the Broker. The service access by the Consumer is being accounted, according to the underlying business model, and the resulting revenue is shared across the involved service providers.
  • Premise (Role): On-Premise operators provide in-house or on-site solutions, which are used within a company (such as ERP) or are offered to business partners under specific terms and conditions. These systems and services are to be regarded as external and legacy to the FIWARE platform, because they do not conform to the architecture and API specifications of FIWARE. They will only be accessible to FIWARE services and applications through the Gateway.
  • Prosumer: A user role able to produce, share and consume their own products and modify/adapt products made by others.
  • Provider (Role): Actor who publishes and offers (provides) certain business functionality on the Web through a service/application endpoint. This role also takes care of maintaining this business functionality.
  • Registry and Repository: Generic enablers that able to store models and configuration information along with all the necessary meta-information to enable searching, social search, recommendation and browsing, so end users as well as services are able to easily find what they need.
  • Revenue Settlement: Process of transferring the actual charges for specific service consumption from the consumer to the service provider.
  • Revenue Sharing: Process of splitting the charges of particular service consumption between the parties providing the specific service (composition) according to a specified revenue sharing model.
  • Service: We use the term service in a very general sense. A service is a means of delivering value to customers by facilitating outcomes customers want to achieve without the ownership of specific costs and risks. Services could be supported by IT. In this case we say that the interaction with the service provider is through a technical interface (for instance a mobile app user interface or a Web service). Applications could be seen as such IT supported Services that often are also composite services.
  • Service Composition: in SOA domain, a service composition is an added value service created by aggregation of existing third party services, according to some predefined work and data flow. Aggregated services provide specialized business functionality, on which the service composition functionality has been split down.
  • Service Delivery Framework: Service Delivery Framework (or Service Delivery Platform (SDP)) refers to a set of components that provide service delivery functionality (such as service creation, session control & protocols) for a type of service. In the context of FIWARE, it is defined as a set of functional building blocks and tools to (1) manage the lifecycle of software services, (2) creating new services by creating service compositions and mashups, (3) providing means for publishing services through different channels on different platforms, (4) offering marketplaces and stores for monetizing available services and (5) sharing the service revenues between the involved service providers.
  • Service Level Agreement (SLA): A service level agreement is a legally binding and formally defined service contract, between a service provider and a service consumer, specifying the contracted qualitative aspects of a specific service (e.g. performance, security, privacy, availability or redundancy). In other words, SLAs not only specify that the provider will just deliver some service, but that this service will also be delivered on time, at a given price, and with money back if the pledge is broken.
  • Store: Part of the Business Framework, offering a set of services that are published to a selected set of marketplaces. The store thereby holds the service portfolio of a specific service provider. In case a specific service is purchased on a service marketplace, the service store handles the actual buying of a specific service (as a financial business transaction).
  • Unified Service Description Language (USDL): USDL is a platform-neutral language for describing services, covering a variety of service types, such as purely human services, transactional services, informational services, software components, digital media, platform services and infrastructure services. The core set of language modules offers the specification of functional and technical service properties, legal and financial aspects, service levels, interaction information and corresponding participants. USDL is offering extension points for the derivation of domain-specific service description languages by extending or changing the available language modules.
Personal tools
Create a book