Page tree

 

 

 

 

 

 

 

Quote Management
API REST Specification

 

Document Number TMF648

October 2017

 

 

 

 

 

 

 

Release: Release 17.5

Status: Member Evaluation

Version: 2.0.0

IPR Mode: RA ND

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

 

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.

 

Direct inquiries to the TM Forum office:

4 Century Drive
Suite 100
Parsippany, NJ 07054, USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

RESOURCE MODEL

Managed Entity and Task Resource Models

Quote resource

Notification Resource Models

Quote Creation Notification

Quote Attribute Value Change Notification

Quote State Change Notification

Quote Remove Notification

Quote Information Required Notification

Quote Approval Required Notification

Quote Agreement Sign -up Required Notification

API OPERATIONS

Operations on Quote

List quotes

Retrieve quote

Create quote

Patch quote

Delete quote

API NOTIFICATIONS

Register listener

Unregister listener

Publish Event to listener

Acknowledgements

Release History

Contributors to Document

List of Tables

 

N/A

 

Introduction

 

The following document is the specification of the REST API for customer quote management. It includes the model definition as well as all available operations. Possible actions are creating, updating and retrieving customer quotes.

The customer Quote API provides a standardized mechanism for placing a customer quote with all of the necessary quote parameters. The API consists of a simple set of operations that interact with CRM/Order Negotiation systems in a consistent manner. A customer quote is created based on a product offer that is defined in a catalog. The quote identifies the product or set of products that are available to a customer, and includes characteristics such as pricing (eventually special pricing for the customer described in the quote), product options and agreement.

Supplier Quote is not managed in the scope of this document.

Quote API performs the following operations on customer quote:

-           Retrieval of a customer quote or a collection of customer quote depending on filter criteria

-           Partial update of a customer quote (including updating rules)

-           Creation of a customer quote (including versioning, default values and creation rules)

-           Deletion of customer quote (for administration purposes)

-           Notification of events on quote

  • Quote creation
  • Quote removal
  • Quote state change
  • Quote value change used to notify that any data in an quote has just changed
  • Quote information required used to notify that some data in the quote need to be filled / are missing
  • Quote is a pending state waiting approval (for the whole quote or only for quote item)
  • quote is accepted by the customer but there is a least one agreement to be signed

 

The following Assumptions were considered in the development of this document :

-           The customer quote management system has access to the commercial catalog system .

 

SAMPLE USE CASES

Reader will find example of use cases using Usage API in “Open Digital Business Scenarios and Use Cases” document.

 

The following table maps out the UC case with Internal/External actors. An internal actor is a representative of the ISP – a external is typically a representative of the prospect/customer.

 

UC

Actor

Rule

A new quote or a new version of a quote is created

Internal

 

An existing quote should be updated or validated before to be send to the customer

Internal

Quote in status In Progress or Pending

An existing quote should be updated after submission to the customer

Internal

External

Only status could be updated

a quote or a collection of quotes should be retrieved

Internal

External (customer)

For an external access special checks and conditions are required (quote status, fields retrieved)

For technical reason a quote should be remove

Internal

 

 

 

 

 


RESOURCE MODEL

Managed Entity and Task Resource Models

Quote resource

Quote can be used to negotiate service and product acquisition or modification between a customer and a service provider. Quote contain list of quote items, a reference to customer (partyRole), a list of productOffering and attached prices and conditions.

Resource model

Lifecycle


Note that an implementation of the specification may enrich the list of states depicted in the diagram. The state machine specifying the typical state change transitions is provided below.


 

Quote State Machine:



 


 

Quote Item State Machine:


 

Note that the quote and quote item states are tightly linked and need to be consistent:

Quote status

Quote item status eligible

In Progress

In Progress

Pending

Pending

In Progress

Validated

Validated

Cancelled

Pending

In Progress

Accepted

Validated

Rejected

Validated

Rejected

 

State definition:

Quote State

Significance

In Progress

The In Progress state is when the quote is currently in the hands of the SP sales team to build it regarding customer requirements. The quote is under construction and needs more information. Everything should be updatable in this state

Pending

The Pending state is used when a quote needs to be validated from the SP perspective for tariff validation or to capture detailed information. The Pending state could be only for some quote items.

Approved

The Approved state is where the quote has been internally approved and sent to the customer. The quote is no longer updatable.

Cancelled

The Cancelled state is when the quote process is stopped from a SP decision. A cancelled quote has never been send to the customer.

Accepted

The Accepted state is used when the customer agreed to commit to the order and signed the quote.

Rejected

The Rejected state is used when the customer does not wish to progress with the quotation. It could his final decision and no other quote will be initiated from this quote or it could be during negotiation phase and a new quote version is triggered from this quote. This new version of the quote is created with the in Progress state.

 

Quote Item State

Significance

In Progress

The In Progress state is when the quote item is currently in the hands of the SP sales team to build it regarding customer requirements. The quote item is under construction and should need more information. Everything should be updatable in this state

Pending

The Pending state is used when a quote item needs to be validated from the SP perspective for tariff validation or to capture detailed information.

Approved

The Approved state is where the quote has been internally approved and sent to the customer. When the quote is shifted to the Approved state, all quote item are marked as Approved

Rejected

The Rejected state is used when the customer does not wish to progress with the quotation. It could be for the whole quote or for only some quote item. If at least one quote item is rejected the quote is rejected.

 

At the quote level it could his final decision and no other quote will be initiated from this quote or it could be during negotiation phase and a new quote version is triggered from this quote. All quote item will be set as In Progress in this new version.

 

 

 

Field descriptions

Quote fields

href

A string. Hyperlink to access the quote.

id

A string. Unique identifier - attributed by quoting system.

externalId

A string. ID given by the consumer and only understandable by him (to facilitate his searches afterwards).

version

A string. Quote version - if the customer rejected the quote but  negotiations still open a new version of the quote is managed.

description

A string. Description of the quote.

category

A string. Used to categorize the quote from a business perspective that can be useful for the CRM system (e.g. "enterprise", "residential", ...).

state

A string. State of the quote : described in the state-machine diagram above.

quoteDate

A date time (DateTime). Date and time when the quote was created.

expectedQuoteCompletionDate

A date (Date). This is expected date - from quote requester - to have a response for this quote.

expectedFulfillmentStartDate

A date (Date). this is the date wished by the requester to have the requested quote item delivered.

effectiveQuoteCompletionDate

A date time (DateTime). Date when the quote has been completed.

validFor

A time period. Quote validity period.

@baseType

A string. Indicates the base (class) type of the quote.

@base

A string. Indicates the (class) type of the quote.

@schemaLocation

A string. Link to the schema describing the REST resource.

note

A list of notes (Note [*]). Extra information about a given entity.

billingAccount

A list of billing account references (BillingAccountRef [*]). A BillingAccount is a detailed description of a bill structure.

agreement

A list of agreement references (AgreementRef [*]). An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.

quoteAuthorization

A list of authorizations (Authorization [*]). If special discount or special product offering price or specific condition need an approval for ISP sale representative it is described here.

relatedParty

A list of related party references (RelatedPartyRef [*]). A related party defines party or party role linked to a specific entity.

contactMedium

A list of contact mediums (ContactMedium [*]). Indicates the contact medium that could be used to contact the party.

quoteItem

A list of quote items (QuoteItem [*]). A quote items describe an action to be performed on a productOffering or a product in order to get pricing elements and condition.

quoteTotalPrice

A list of quote prices (QuotePrice [*]). Description of price and discount awarded.

Attachment sub-resource

Complements the description of an element (for instance a product) through video, pictures...

description

A string. A narrative text describing the content of the attachment.

href

A string. Reference of the attachment.

id

A string. Unique identifier of the attachment.

type

A string. Attachment type such as video, picture.

url

A string. Uniform Resource Locator, is a web page address (a subset of URI).

@baseType

A string. Indicates the base (class) type of the attachment.

@type

A string. Indicates the (class) type of the attachment.

@schemaLocation

A string. Link to schema describing this REST resource.

Authorization sub-resource

If special discount or special product offering price or specific condition need an approval for ISP sale representative it is described here.

authorizationName

A string. Name of the required authorization.

authorizationState

A string. State of the authorization - could be approved or declined.

authorizationRequestedDate

A date (Date). Date when the authorization is requested for.

authorizationGivenDate

A date (Date). Date when the authorization (approved or declined) has been done.

authorizationSignatureRepresentation

A string. To described a digital or manual signature.

@type

A string. Indicates the (class) type of the authorization.

@schemaLocation

A string. Link to the schema describing the REST resource.

approver

A list of related party references (RelatedPartyRef [1..*]). A related party defines party or party role linked to a specific entity.

ContactMedium sub-resource

Indicates the contact medium that could be used to contact the party.

preferred

A boolean. If true, indicates that is the preferred contact medium.

type

A string. Type of the contact medium, such as: email address, telephone number, postal address.

validFor

A time period. The time period that the contact medium is valid for.

characteristic

A medium characteristic (MediumCharacteristic). Describes the contact medium characteristics that could be used to contact a party (an individual or an organization).

MediumCharacteristic sub-resource

Describes the contact medium characteristics that could be used to contact a party (an individual or an organization).

city

A string. The city.

country

A string. The country.

emailAddress

A string. Full email address in standard format.

type

A string. Type of medium (fax, mobile phone...).

postCode

A string. Postcode.

stateOrProvince

A string. State or province.

street1

A string. Describes the street.

street2

A string. Complementary street description.

faxNumber

A string. The fax number of the contact.

phoneNumber

A string. The primary phone number of the contact.

@type

A string. Indicates the (class) type of the medium characteristic.

@schemaLocation

A string. Link to the schema describing this REST resource.

Money sub-resource

A base / value business entity used to represent money.

value

A float. A positive floating point number.

unit

A string. Currency (ISO4217 norm uses 3 letters to define the currency).

Note sub-resource

Extra information about a given entity.

date

A date time (DateTime). Date of the note.

author

A string. Author of the note.

text

A string. Text of the note.

Price sub-resource

Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.

taxIncludedAmount

A money (Money). All taxes included amount (expressed in the given currency).

dutyFreeAmount

A money (Money). All taxes excluded amount (expressed in the given currency).

taxRate

A float. Tax rate.

@type

A string. Indicates the (class) type of the price.

percentage

A float. Percentage to apply for ProdOfferPriceAlteration.

@schemaLocation

A string. Link to the schema describing this REST resource.

PriceAlteration sub-resource

Is an amount, usually of money, that modifies the price charged for an order item.

name

A string. A short descriptive name such as "Monthly discount".

description

A string. A narrative that explains in detail the semantics of this order item price alteration.

priceType

A string. A category that describes the price such as recurring, one time and usage.

unitOfMeasure

A string. Could be minutes, GB...

recurringChargePeriod

A string. Could be month, week...

applicationDuration

An integer. Duration during which the alteration applies on the order item price (for instance 2 months free of charge for the recurring charge).

priority

An integer. Priority level for applying this alteration among all the defined alterations on the order item price.

priceCondition

A string. Condition that triggers the price application.

validFor

A time period. The period for which the price alteration is valid.

@type

A string. Indicates the (class) type of the price alteration.

@schemaLocation

A string. Link to the schema describing this REST resource.

price

A price (Price). Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.

ProductCharacteristic sub-resource

Characteristics of the product to instantiate or to modify.

name

A string. Name of the characteristic.

value

A stringor object (StringorObject). Value of the characteristic.

@type

A string. Indicates the (class) type of resource.

@schemaLocation

A string. This field provided a link to the schema describing this REST resource.

ProductRefOrValue sub-resource

Product reference. 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.

href

A string. Reference of the product.

id

A string. Unique identifier of the product.

name

A string. Name of the product.

productRelationship

A list of product ref or value relationships (ProductRefOrValueRelationship [*]). Represents a relationship between products - which potentially holds an entire product object or a product reference (with partial content).

place

A list of place references (PlaceRef [*]). Place defines the places where the products are sold or delivered.

characteristic

A list of product characteristics (ProductCharacteristic [*]). Characteristics of the product to instantiate or to modify.

relatedParty

A list of related party references (RelatedPartyRef [*]). A related party defines party or party role linked to a specific entity.

productSpecification

A product specification reference (ProductSpecificationRef). A ProductSpecification is a detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to customers or other parties playing a party role.

ProductRefOrValueRelationship sub-resource

Represents a relationship between products - which potentially holds an entire product object or a product reference (with partial content).

type

A string. 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

A product ref or value (ProductRefOrValue). Product reference. 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.

QuoteItem sub-resource

A quote items describe an action to be performed on a productOffering or a product in order to get pricing elements and condition.

id

A string. Identifier of the quote item (generally it is a sequence number 01, 02, 03, ...).

state

A string. State of the quote item : described in the state machine diagram.

action

A string. Action to be perfomed on this quote item (add, modify, remove, etc.).

quantity

An Integer. Indicates the quantity to be quoted.

@type

A string. Indicates the base (class) type of the quote Item.

@schemaLocation

A string. Link to the schema describing this REST resource.

quoteItemRelationship

A list of quote item relationships (QuoteItemRelationship [*]). Used to describe relationship between quote item. These relationship could have an impact on pricing and conditions.

attachment

A list of attachments (Attachment [*]). Complements the description of an element (for instance a product) through video, pictures...

quoteItemAuthorization

A list of authorizations (Authorization [*]). If special discount or special product offering price or specific condition need an approval for ISP sale representative it is described here.

note

A list of notes (Note [*]). Extra information about a given entity.

relatedParty

A list of related party references (RelatedPartyRef [*]). A related party defines party or party role linked to a specific entity.

appointment

A list of appointment references (AppointmentRef [*]).

productOffering

A product offering reference (ProductOfferingRef). A product offering represents entities that are orderable from the provider of the catalog, this resource includes pricing information.

quoteItemPrice

A list of quote prices (QuotePrice [*]). Description of price and discount awarded.

product

A product ref or value (ProductRefOrValue). Product reference. 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.

QuoteItemRelationship sub-resource

Used to describe relationship between quote item. These relationship could have an impact on pricing and conditions.

id

A string. ID of the related order item (must be in the same quote).

type

A string. Relationship type as relies on, bundles, etc...

QuotePrice sub-resource

Description of price and discount awarded.

priceType

A string. indicate if the price is for recurrent or no-recurrent charge.

recurringChargePeriod

A string. Used for recurring charge to indicate period (month, week, etc..).

unitOfMeasure

A string. Unit of Measure if price depending on it (Gb, SMS volume, etc..).

name

A string. Name of the quote /quote item price.

description

A string. Description of the quote/quote item price.

@type

A string. Indicates the base (class) type of the quote price.

@schemaLocation

A string. link to the schema describing this REST resource.

priceAlteration

A list of price alterations (PriceAlteration [*]). Is an amount, usually of money, that modifies the price charged for an order item.

price

A price (Price). Provides all amounts (tax included, duty free, tax rate), used currency and percentage to apply for Price Alteration.

AgreementRef relationship

Agreement reference. An agreement represents a contract or arrangement, either written or verbal and sometimes enforceable by law, such as a service level agreement or a customer price agreement. An agreement involves a number of other business entities, such as products, services, and resources and/or their specifications.

href

A string. Reference of the agreement.

id

A string. Identifier of the agreement.

name

A string. Name of the agreement.

@type

A string. Indicates the (class) type of the agreement.

AppointmentRef relationship

 

href

A string. Hyperlink to access the appointment.

id

A string. Identifier of the appointment (generally it is a sequence number 01, 02, 03, ...).

description

A string. An explanatory text regarding the appointment made with a party.

BillingAccountRef relationship

BillingAccount reference. A BillingAccount is a detailed description of a bill structure.

id

A string. Unique identifier of the billing account.

href

A string. Reference of the billing account.

name

A string. Name of the billing account.

@type

A string. Indicates the (class) type of the billing account.

PlaceRef relationship

Place reference. Place defines the places where the products are sold or delivered.

id

A string. Unique identifier of the place.

href

A string. Unique reference of the place.

name

A string. A user-friendly name for the place, such as "Paris Store", "London Store", "Main Home".

role

A string. Role of the place (for instance: 'home delivery', 'shop retrieval').

ProductOfferingRef relationship

ProductOffering reference. A product offering represents entities that are orderable from the provider of the catalog, this resource includes pricing information.

id

A string. Unique identifier of the product offering.

href

A string. Reference of the product offering.

name

A string. Name of the product offering.

@type

A string. Indicate the class (type) of product offering.

ProductSpecificationRef relationship

Product specification reference: A ProductSpecification is a detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to customers or other parties playing a party role.

id

A string. Unique identifier of the product specification.

href

A string. Reference of the product specification.

version

A string. Version of the product specification.

name

A string. Name of the product specification.

@type

A string. Indicates the (class) type of resource (here product specification).

RelatedPartyRef relationship

A related party defines party or party role linked to a specific entity.

id

A string. Unique identifier of a related party.

href

A string. Reference of the related party, could be a party reference or a party role reference.

role

A string. Role of the related party.

name

A string. Name of the related party.

@type

A string. Indicates the base (class) type of the party.

Json representation sample

We provide below the json representation of an example of a 'Quote' resource object

This example features:

  • A global authorization
  • 3 quote items:
    • For 10 lines with TMF Tarif plan – 10% off
    • For 10 handsets
    • For a support free for the 12 first months.

{
    "href": "https://host:port/quote/quote/6069",
    "id": "6069",
    "externalId": "742",
    "version": "1.0",
    "description": "This is the quote",
    "category": "Telco Quote",
    "state": "Approved",
    "quoteDate": "2017-09-18T00:00",
    "expectedQuoteCompletionDate": "2017-09-21",
    "expectedFulfillmentStartDate": "2017-10-01”,
    "effectiveQuoteCompletionDate": "2017-09-20T00:00",
    "validFor": {
        "startDateTime": "2017-09-20T00:00",
        "endDateTime": "2018-04-20T00:00"
    },
    "@baseType": "Quote",
    "@base": "Quote",
    "@schemaLocation": "www.quote.quote.json",
    "note": [
        {
            "date": "2017-09-22T00:00",
            "author": "Mr Hide",
            "text": " Quote following serviceability #2345"
        }
    ],
    "billingAccount": [
        {
            "id": "4850",
            "href": "https://host:port/onboardingManagement/billingAccount/4850",
            "name": "Horizon Account",
            "@type": "BillingAccount"
        }
    ],
    "agreement": [
        {
            "href": "https://host:port/onboardingManagement/agreement/6596",
            "id": "6596",
            "name": "Standard Disclaimer",
            "@type": "DisclaimerAgreement"
        }
    ],
    "quoteAuthorization": [
        {
            "authorizationName": "GlovalQuoteApproval",
            "authorizationState": "approved",
            "authorizationRequestedDate": "2017-09-20",
            "authorizationGivenDate": "2017-09-20",
            "authorizationSignatureRepresentation": "manual",
            "@type": "QuoteAuthorization",
            "approver": [
                {
                    "id": "5938",
                    "href": "https://host:port/partyManagement/organization/5938",
                    "role": "Sale Manager",
                    "name": "Jean Pontus",
                    "@type": "IndividualParty"
                }
            ]
        }
    ],
    "relatedParty": [
        {
            "id": "7737",
            "href": "https://host:port/partyManagement/individual/7737",
            "role": "Quote contact",
            "name": "Jimmy Doe",
            "@type": " IndividualParty"
        },

        {
            "id": "11",
            "href": "https://host:port/partyManagement/organization/11",
            "role": "Requester",
            "name": "Horizon LtD",
            "@type": " organizationParty"
        }

    ],
    "contactMedium": [
        {
            "preferred": true,
            "type": " TelephoneNumber ",
            "characteristic": [
                {
                    "phoneNumber": "04569885552"
                }
            ]
        }
    ],
    "quoteItem": [
        {
            "id": "1",
            "state": "approved",
            "action": "add",

             "quantity": "10",
            "@type": "QuoteItem",
            "attachment": [
                {
                    "description": "TMF Tariff Plan",
                    "href": "http://hostname:port/documentManagement/attachment/22",
                    "id": "22",
                    "type": "Document",
                    "url": "http://xxxxx"
                }
            ],
            "quoteItemAuthorization": [
                {
                    "authorizationName": "DiscountCompany",
                    "authorizationState": "approved",
                    "authorizationRequestedDate": "2017-09-20",
                    "authorizationGivenDate": "2017-09-20",
                    "authorizationSignatureRepresentation": "digital",
                    "approver": [
                        {
                            "id": "3298",
                            "href": "https://host:port/partyManagement/organization/3298",
                            "role": "Discount Approver",
                            "name": "Richard Cole"
                        }
                    ]
                }
            ],
            "appointment": [
                {
                    "href": "http://hostname:port/appointmentManagement/appointment/111",
                    "id": "111",
                    "description": "This  appointment to present advantage of solution "
                }
            ],
            "productOffering": {
                "id": "5295",
                "href": "https://host:port/productOffering/productOffering/5295",
                "name": "TMF Tariff plan ",
                "@type": "TMFTariffPlanPO"
            },
            "quoteItemPrice": [
                {
                    "priceType": "recurring",
                    "recurringChargePeriod": "monthly",
                    "name": "TMFTPM",
                    "description": "Recurring fee for TMF",
                    "@type": "QuoteItemPrice",
                    "priceAlteration": [
                        {
                            "name": "Corporate Discount",
                            "description": "This  price alteration ...",
                            "priceType": Recurring",
                            "recurringChargePeriod": "monthly",
                            "priority": 1,
                            "priceCondition": "Only applicable if 10 or more ordered",
                            "@type": "PriceAlteration",
                            "price": {
                                "percentage": 10.0,
                            }
                        }
                    ],
                    "price": {
                        "taxIncludedAmount": "36",
                        "dutyFreeAmount": "30",
                        "taxRate": 20,
                    }
                }
            ],
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "href": "https://host:port/productSpecification/productSpecification/2489",
                    "version": "1.5",
                    "name": "RTMFPlan",
                    "@type": "ProductSpec"
                }
            }
        },

 

        {
            "id": "2",
            "state": "approved",
            "action": "add",

             "quantity": "10",
            "@type": " QuoteItem...",
            "productOffering": {
                "id": "63",
                "href": "https://host:port/productOffering/productOffering/63",
                "name": "Nice Handset",
                "@type": "Handset"
            },
            "quoteItemPrice": [
                {
                    "priceType": "oneOff",
                    "name": "Nice Phone",
                    "description": "This  quote price ...",
                    "price": {
                        "taxIncludedAmount": "480",
                        "dutyFreeAmount": "400",
                        "taxRate": 20,

                    }
                }
            ],
            "product": {
                "name": "Nice Phone",
                "characteristic": [
                    [
                        {
                            "name": "Colour",
                            "value": "black"
                        },
                        {
                            "name": "Memory",
                            "value": "32"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "9",
                    "href": "https://host:port/productSpecification/productSpecification/9",
                    "version": "3.0",
                    "name": "NicePhone",

                    "@type": "ProductSpec"
                }
            }
        },

 

        {
            "id": "3",
            "state": "approved",
            "action": "add",
            "quantity": 1,
            "productOffering": {
                "id": "85",
                "href": "https://host:port/productOffering/productOffering/85",
                "name": "24/7/7 Support"
            },
            "quoteItemPrice": [
                {
                    "priceType": "recurring",
                    "recurringChargePeriod": "monthly",
                    "name": "247 Sypport
                    "description": "This  quote price ...",
                    "priceAlteration": [
                        {
                            "name": "Discount",
                            "description": "This  price alteration ...",
                            "priceType": "recurring
                            "recurringChargePeriod": "monthly",
                            "applicationDuration": 12,
                            "priority": 1,
                            "priceCondition": "free support 12 first months",
                            "price": {
                                "percentage": 100.0,
                            }
                        }
                    ],
                    "price": {
                        "taxIncludedAmount": "24",
                        "dutyFreeAmount": "20",
                        "taxRate": 20
                    }
                }
            ],
            "product": {
                "name": "Silver Support",
                "characteristic": [
                    [
                        {
                            "name": "Time to respond",
                            "value": "4H"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "289",
                    "href": "https://host:port/productSpecification/productSpecification/289",
                    "version": "1.5",
                    "name": "Support",
                    "@type": "ProductSpec"
                }
            }
        }
    ]
}

 

Notification Resource Models

 

7 notifications are defined for this API

Notifications related to Quote:
    - QuoteCreationNotification
    - QuoteAttributeValueChangeNotification
    - QuoteStateChangeNotification
    - QuoteRemoveNotification
    - QuoteInformationRequiredNotification
    - QuoteApprovalRequiredNotification
    - QuoteAgreementSign-upRequiredNotification

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification resource (depicted by "SpecificNotification" placeholder) is a sub class of a generic Notification structure containing an id of the event occurence (eventId), an event timestamp (eventTime), and the name of the notification resource (eventType).
This notification structure owns an event structure ("SpecificEvent" placeholder) linked to the resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

Quote Creation Notification

Notification sent when a new Quote resource is created.

Json representation sample

We provide below the json representation of an example of a 'QuoteCreationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteCreationNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote Attribute Value Change Notification

Notification sent when changing an attribute of a Quote resource.

Json representation sample

We provide below the json representation of an example of a 'QuoteAttributeValueChangeNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteAttributeValueChangeNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote State Change Notification

Notification sent when changing the state of a Quote resource.

Json representation sample

We provide below the json representation of an example of a 'QuoteStateChangeNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteStateChangeNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote Remove Notification

Notification sent when removing a Quote resource.

Json representation sample

We provide below the json representation of an example of a 'QuoteRemoveNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteRemoveNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote Information Required Notification

Notification sent when information from user is required concerning a Quote resource

Json representation sample

We provide below the json representation of an example of a 'QuoteInformationRequiredNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteInformationRequiredNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote Approval Required Notification

Notification approval required case for resource Quote

Json representation sample

We provide below the json representation of an example of a 'QuoteApprovalRequiredNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteApprovalRequiredNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

Quote Agreement Sign -up Required Notification

Notification agreement sign-up required case for resource Quote

Json representation sample

We provide below the json representation of an example of a 'QuoteAgreementSign-upRequiredNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"QuoteAgreementSign-upRequiredNotification",
     "event": {
        "quote" :
            {-- SEE Quote RESOURCE SAMPLE --}
    }
}
 

 

 

  API OPERATIONS

Remember the following Uniform Contract:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

 

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to execute Task Resources

Other Request Methods

POST on TASK Resource

GET and POST must not be used to tunnel other request methods.

 

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

 

Operations on Quote

List quotes

  GET /quote?fields=...&{filtering}

Description

This operation is used to retrieve quote information using filter criteria. 

If the version is not filled, by default only the most current version is returned.

Filtering selection is enabled on all first level attributes but not on inner classes with the exception of relatedParties.

Filtering may optionally be enabled on all attributes and inner classes.

Attribute selection is enabled on all first level attributes but not on inner classes.

Attribute selection may optionally be enabled on all attributes and inner classes.

Specific Quote behavior:

Special conditions apply if the API consumer is an external system or actor – in this case:

  • only Approved , Accepted and Rejected quote should be retrieved.
  • only quote last version should be retrieved.
  • a filter should be applied on the response to remove fields with only internal use as for example all information related to the authorization or the ISP parties linked to the quote.

If the API is an internal system or actor:

  • If the quote ID is filled but without version – all quote versions are retrieved in the response.

Generic behavior :

  • Return status codes
    • 200 OK - the request was successful (includes situation in which no quote matched supplied criteria)
    • 400 Bad Request - error

 

Usage Samples

Here's an example of a request for retrieving Quote resources.

Get all quote id in approved state

 


Request
 

GET /quoteManagement/quote?fields=state&state="approved"
Accept: application/json

 


Response
 

200

[
    {
        "id": "123"
    },
    {
        "id": "452"
    },
    {
        "id": "741"
    }
]
 

Retrieve quote

  GET /quote/{id}?fields=...&{filtering}

Description

This operation is used to retrieve quote information using the ID. If the version is not filled, by default only the most current version is returned. To get a specific version of an entity the (Version=X) directive is added to the ID – example to get the Quote versioned 1.1 we could use /quoteManagement/Quote/id=42:(Version=1.1)

Note that the resources in this case may have the same ID but may be distinguished by the inclusion of the version number in their ID i.e /42:(version=1.0), /42:(version=2.0).

Attribute selection is enabled on all first level attributes but not on inner classes.

Attribute selection may optionally be enabled on all attributes and inner classes.

Behavior :

  • Return status codes
    • 200 OK - the request was successful
    • 404 Not found - the supplied ID does not match a known Quote

 

Use case : Get a specific quote based on its ID

Special conditions apply if the API consumer is an external system or actor – in this case:

  • only Approved , Accepted and Rejected quote should be retrieved.
  • only quote last version should be retrieved.
  • a filter should be applied on the response to remove fields with only internal use as for example all information related to the authorization or the ISP parties linked to the quote.

If the API is an internal system or actor:

If the quote ID is filled but without version – all quote versions are retrieved in the response

 

Usage Samples

Here's an example of a request for retrieving a Quote resource.


Request
 

GET /quoteManagement/quote/6069
Accept: application/json

 


Response
 

200

{
    "href": "https://host:port/quote/quote/6069",
    "id": "6069",
    "externalId": "742",
    "version": "3.0",
    "description": "This is the quote",
    "category": "Telco Quote",
    "state": "Approved",
    "quoteDate": "2017-09-18T00:00",
    "expectedQuoteCompletionDate": "2017-09-21",
    "expectedFulfillmentStartDate": "2017-10-01”,
    "effectiveQuoteCompletionDate": "2017-09-20T00:00",

     "validFor": {
        "startDateTime": "2017-09-20T00:00",
        "endDateTime": "2018-04-20T00:00"
    },
    "@baseType": "Quote",
    "@base": "Quote",
    "@schemaLocation": "www.quote.quote.json",
    "note": [
        {
            "date": "2017-09-22T00:00",
            "author": "Mr Hide",
            "text": " Quote following serviceability #2345"
        }
    ],
    "billingAccount": [
        {
            "id": "4850",
            "href": "https://host:port/onboardingManagement/billingAccount/4850",
            "name": "Horizon Account",
            "@type": "BillingAccount"
        }
    ],
    "agreement": [
        {
            "href": "https://host:port/onboardingManagement/agreement/6596",
            "id": "6596",
            "name": "Standard Disclaimer",
            "@type": "DisclaimerAgreement"
        }
    ],
    "relatedParty": [
        {
            "id": "7737",
            "href": "https://host:port/partyManagement/individual/7737",
            "role": "Quote contact",
            "name": "Jimmy Doe",
            "@type": " IndividualParty"
        },

        {
            "id": "11",
            "href": "https://host:port/partyManagement/organization/11",
            "role": "Requester",
            "name": "Horizon LtD",
            "@type": " organizationParty"
        }

    ],
    "contactMedium": [
        {
            "preferred": true,
            "type": " TelephoneNumber ",
            "characteristic": [
                {
                    "phoneNumber": "04569885552"
                }
            ]
        }
    ],
    "quoteItem": [
        {
            "id": "1",
            "state": "approved",
            "action": "add",

             "quantity": "10",
            "@type": "QuoteItem",
            "attachment": [
                {
                    "description": "TMF Tariff Plan",
                    "href": "http://hostname:port/documentManagement/attachment/22",
                    "id": "22",
                    "type": "Document",
                    "url": "http://xxxxx"
                }
            ],
            "appointment": [
                {
                    "href": "http://hostname:port/appointmentManagement/appointment/111",
                    "id": "111",
                    "description": "This  appointment to present advantage of solution "
                }
            ],
            "productOffering": {
                "id": "5295",
                "href": "https://host:port/productOffering/productOffering/5295",
                "name": "TMF Tariff plan ",
                "@type": "TMFTariffPlanPO"
            },
            "quoteItemPrice": [
                {
                    "priceType": "recurring",
                    "recurringChargePeriod": "monthly",
                    "name": "TMFTPM",
                    "description": "Recurring fee for TMF",
                    "@type": "QuoteItemPrice",
                    "priceAlteration": [
                        {
                            "name": "Corporate Discount",
                            "description": "This  price alteration ...",
                            "priceType": Recurring",
                            "recurringChargePeriod": "monthly",
                            "priority": 1,
                            "priceCondition": "Only applicable if 10 or more ordered",
                            "@type": "PriceAlteration",
                            "price": {
                                "percentage": 10.0,
                            }
                        }
                    ],
                    "price": {
                        "taxIncludedAmount": "36",
                        "dutyFreeAmount": "30",
                        "taxRate": 20,
                    }
                }
            ],
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "href": "https://host:port/productSpecification/productSpecification/2489",
                    "version": "1.5",
                    "name": "RTMFPlan",
                    "@type": "ProductSpec"
                }
            }
        },

 

        {
            "id": "2",
            "state": "approved",
            "action": "add",

             "quantity": "10",
            "@type": " QuoteItem...",
            "productOffering": {
                "id": "63",
                "href": "https://host:port/productOffering/productOffering/63",
                "name": "Nice Handset",
                "@type": "Handset"
            },
            "quoteItemPrice": [
                {
                    "priceType": "oneOff",
                    "name": "Nice Phone",
                    "description": "This  quote price ...",
                    "price": {
                        "taxIncludedAmount": "480",
                        "dutyFreeAmount": "400",
                        "taxRate": 20,

                    }
                }
            ],
            "product": {
                "name": "Nice Phone",
                "characteristic": [
                    [
                        {
                            "name": "Colour",
                            "value": "black"
                        },
                        {
                            "name": "Memory",
                            "value": "32"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "9",
                    "href": "https://host:port/productSpecification/productSpecification/9",
                    "version": "3.0",
                    "name": "NicePhone",

                    "@type": "ProductSpec"
                }
            }
        },

 

        {
            "id": "3",
            "state": "approved",
            "action": "add",
            "quantity": 1,
            "productOffering": {
                "id": "85",
                "href": "https://host:port/productOffering/productOffering/85",
                "name": "24/7/7 Support"
            },
            "quoteItemPrice": [
                {
                    "priceType": "recurring",
                    "recurringChargePeriod": "monthly",
                    "name": "247 Sypport
                    "description": "This  quote price ...",
                    "priceAlteration": [
                        {
                            "name": "Discount",
                            "description": "This  price alteration ...",
                            "priceType": "recurring
                            "recurringChargePeriod": "monthly",
                            "applicationDuration": 12,
                            "priority": 1,
                            "priceCondition": "free support 12 first months",
                            "price": {
                                "percentage": 100.0,
                            }
                        }
                    ],
                    "price": {
                        "taxIncludedAmount": "24",
                        "dutyFreeAmount": "20",
                        "taxRate": 20
                    }
                }
            ],
            "product": {
                "name": "Silver Support",
                "characteristic": [
                    [
                        {
                            "name": "Time to respond",
                            "value": "4H"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "289",
                    "href": "https://host:port/productSpecification/productSpecification/289",
                    "version": "1.5",
                    "name": "Support",
                    "@type": "ProductSpec"
                }
            }
        }
    ]
}
 

Create quote

  POST /quote

Description

This operation is used to create a new quote (V1.0) or a new version of an existing quote (Vn.n n=> 1)

ID Management :

For a quote in V1.0 POST should be used without specifying the id, the quote system is in charge of generating the id.

For a quote creation in other version than V1.0, the id should be specified.

In all case the href should not be filled because , the quote system is in charge of generating href for the new version of the Quote

Mandatory and Non Mandatory Attributes

The following tables provide the list of mandatory and non-mandatory attributes when creating a Quote, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

quoteItem

 

 

Non Mandatory Attributes

Default Value

Rule

externalId

N/A

 

version

1

See specific rule above.

Version should be consistent with previous version

description

N/A

 

category

“uncategorized”

 

state

 

Attributed by server side

quoteDate

 

Attributed by server side

expectedQuoteCompletionDate

 

 

expectedFulfillmentStartDate

 

 

effectiveQuoteCompletionDate

 

Attributed by server side

validFor

 

 

note

N/A

 

billingAccount

N/A

 

agreement

 

 

quoteAuthorization

 

Attributed by server side

relatedParty

 

 

contactMedium

N/A

 

quoteTotalPrice

 

Attributed by server side

 

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships when creating a Quote resource.

Context

Mandatory Sub-Attributes

quoteItem

action

quoteItem.quoteItem

id, action

note

text

agreement

id OR href

billingAccount

id OR href

relatedParty

role

quoteItem.productOffering

id OR href

quoteItem.appointment

id OR href

quoteItem.product

id OR href

 

 

The following pre-conditions apply for this operation.

Pre-conditions

PATCH allowed if quote not accepted or rejected

 

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional attributes of the resource (or sub-resources).

Attributes

Default Value

version

1

 

Usage Samples

Here's an example of a request for creating a Quote resource. In this example the request only passes mandatory attributes.


Request
 

POST /quoteManagement/quote
Content-Type: application/json

{
    "externalId": "742",
    "version": "1.0",
    "description": "This is the quote",
    "category": "Telco Quote",
    "expectedQuoteCompletionDate": "2017-09-21",
    "expectedFulfillmentStartDate": "2017-10-01",
    "@baseType": "Quote",
    "@base": "Quote",
    "@schemaLocation": "www.quote.quote.json",
    "note": [
        {
            "date": "2017-09-22T00:00",
            "author": "Mr Hide",
            "text": " Quote following serviceability #2345"
        }
    ],
    "billingAccount": [
        {
            "id": "4850",
            "href": "https://host:port/onboardingManagement/billingAccount/4850",
            "name": "Horizon Account",
            "@type": "BillingAccount"
        }
    ],
    "relatedParty": [
        {
            "id": "7737",
            "href": "https://host:port/partyManagement/individual/7737",
            "role": "Quote contact",
            "name": "Jimmy Doe",
            "@type": " IndividualParty"
        },

        {
            "id": "11",
            "href": "https://host:port/partyManagement/organization/11",
            "role": "Requester",
            "name": "Horizon LtD",
            "@type": " organizationParty"
        }
    ],
    "contactMedium": [
        {
            "preferred": true,
            "type": " TelephoneNumber ",
            "characteristic": [
                {
                    "phoneNumber": "04569885552"
                }
            ]
        }
    ],
    "quoteItem": [
        {
            "id": "1",
            "action": "add",

             "quantity": "10",
            "productOffering": {
                "id": "5295",
                "name": "TMF Tariff plan "
            },
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "version": "1.0"
                }
            }
        },

        {
            "id": "2",
            "action": "add",

             "quantity": "10",
            "productOffering": {
                "id": "63",
                "name": "Nice Handset"
            },
            "product": {
                "name": "Nice Phone",
                "characteristic": [
                    [
                        {
                            "name": "Memory",
                            "value": "32"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "9",
                    "name": "NicePhone"
                }
            }
        },

        {
            "id": "3",
            "action": "add",
            "quantity": 1,
            "productOffering": {
                "id": "85",
                "name": "24/7/7 Support"
            },
            "product": {
                "name": "Silver Support",
                "productSpecification": {
                    "id": "289",
                    "name": "Support"
                }
            }
        }
    ]
}


 


Response
 

201

{
    "href": "https://host:port/quote/quote/6069",
    "id": "6069",
    "externalId": "742",
    "version": "1.0",
    "description": "This is the quote",
    "category": "Telco Quote",
    "state": "In Progress",
    "quoteDate": "2017-09-18T00:00",
    "expectedQuoteCompletionDate": "2017-09-21",
    "expectedFulfillmentStartDate": “2017-10-01”,
    "@baseType": "Quote",
    "@base": "Quote",
    "@schemaLocation": "www.quote.quote.json",
    "note": [
        {
            "date": "2017-09-22T00:00",
            "author": "Mr Hide",
            "text": " Quote following serviceability #2345"
        }
    ],
    "billingAccount": [
        {
            "id": "4850",
            "href": "https://host:port/onboardingManagement/billingAccount/4850",
            "name": "Horizon Account",
            "@type": "BillingAccount"
        }
    ],
    "relatedParty": [
        {
            "id": "7737",
            "href": "https://host:port/partyManagement/individual/7737",
            "role": "Quote contact",
            "name": "Jimmy Doe",
            "@type": " IndividualParty"
        },

        {
            "id": "11",
            "href": "https://host:port/partyManagement/organization/11",
            "role": "Requester",
            "name": "Horizon LtD",
            "@type": " organizationParty"
        }

    ],
    "contactMedium": [
        {
            "preferred": true,
            "type": " TelephoneNumber ",
            "characteristic": [
                {
                    "phoneNumber": "04569885552"
                }
            ]
        }
    ],
    "quoteItem": [
        {
            "id": "1",
            "state": "In Progress ",
            "action": "add",

             "quantity": "10",
            "@type": "QuoteItem",
            "productOffering": {
                "id": "5295",
                "href": "https://host:port/productOffering/productOffering/5295",
                "name": "TMF Tariff plan ",
                "@type": "TMFTariffPlanPO"
            },
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "name": "RTMFPlan"
                }
            }
        },

 

        {
            "id": "2",
            "state": " In Progress ",
            "action": "add",

             "quantity": "10",
            "@type": " QuoteItem...",
            "productOffering": {
                "id": "63",
                "name": "Nice Handset",
            },
            "product": {
                "name": "Nice Phone",
                "characteristic": [
                    [
                        {
                            "name": "Memory",
                            "value": "32"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "9",
                    "name": "NicePhone",
                }
            }
        },

 

        {
            "id": "3",
            "state": " In Progress ",
            "action": "add",
            "quantity": 1,
            "productOffering": {
                "id": "85",
                "href": "https://host:port/productOffering/productOffering/85",
                "name": "24/7/7 Support"
            },
            "product": {
                "name": "Silver Support",
                "characteristic": [
                    [
                        {
                            "name": "Time to respond",
                            "value": "4H"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "289",
                    "name": "Support"
                }
            }
        }
    ]
}
 

Patch quote

  PATCH /quote/{id}

Description

This operation allows partial updates of a quote entity. Support of json/merge (https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH operation.  Hence these tables are not repeated here.

This operation is used to modify quote and/or their items. 

By default PATCH will be acting only on the latest version of the Resource.

To update a specific version of an entity the (Version=X) directive is added to the ID (i.e /id:(version=x). Note that this capability is only available to API users having the proper authorizations to change the catalog entities with specific version numbers.

Behavior :

  • Return status codes
    • 200 OK - the request was successful

400 Bad Request - error

 

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non-patchable attributes, including constraint rules on their usage.

Patchable Attributes

Rule

description

Only when quote is In Progress or Pending state

category

Only when quote is In Progress or Pending state

state

To manage the quote lifecycle: in progress, pending, approved, rejected, accepted, cancelled.

Influence the quoteItem state – see following consistency table

externalId

 

expectedQuoteCompletionDate

Only when quote is In Progress or Pending state

expectedFulfillmentStartDate

Only when quote is In Progress or Pending state

note

 

billingAccount

 

relatedParty

 

contactMedium

 

agreement

Only when quote is Approved state

quoteItem

Only when quote is In Progress or Pending state

quoteItem.quantity

Only when quote is In Progress or Pending state

quoteItem.productOfferingRef

Only when quote is In Progress or Pending state

quoteItem.product

Only when quote is In Progress or Pending state

quoteItem.product.characteristic

Only when quote is In Progress or Pending state

quoteItem.product.productRelationship

Only when quote is In Progress or Pending state

quoteItem.appointment

Only when quote is In Progress or Pending state

 

Non Patchable Attributes

Rule

id

 

href

 

version

 

quoteDate

This date should be automatically filled and not modifiable

effectiveQuoteCompletionDate

This date should be automatically filled and not modifiable

quoteTotalPrice

 

quoteAuthorization

 

validFor

quotePrice

 

quoteItemPrice

 

 

Additional Rules

The following pre-conditions apply for this operation.

Pre-conditions

PATCH allowed if quote not accepted or rejected

 

Usage Samples

Here's an example of a request for patching a Quote resource – in this example the quantity is modified (from 10 to 15).


Request
 

PATCH /quoteManagement/quote/6069
Content-Type: application/merge-patch+json

{
    "id": "6069",

    "quoteItem": [
        {
            "id": "1",
            "action": "add",

             "quantity": "15",
            "productOffering": {
                "id": "5295",

                "name": "TMF Tariff plan "
            },
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "name": "RTMFPlan"
                }
            }
        }

    ]
}


 


Response
 

201

{
    "href": "https://host:port/quote/quote/6069",
    "id": "6069",
    "externalId": "742",
    "version": "1.0",
    "description": "This is the quote",
    "category": "Telco Quote",
    "state": "In Progress",
    "quoteDate": "2017-09-18T00:00",
    "expectedQuoteCompletionDate": "2017-09-21",
    "expectedFulfillmentStartDate": “2017-10-01”,
    "@baseType": "Quote",
    "@base": "Quote",
    "@schemaLocation": "www.quote.quote.json",
    "note": [
        {
            "date": "2017-09-22T00:00",
            "author": "Mr Hide",
            "text": " Quote following serviceability #2345"
        }
    ],
    "billingAccount": [
        {
            "id": "4850",
            "href": "https://host:port/onboardingManagement/billingAccount/4850",
            "name": "Horizon Account",
            "@type": "BillingAccount"
        }
    ],
    "relatedParty": [
        {
            "id": "7737",
            "href": "https://host:port/partyManagement/individual/7737",
            "role": "Quote contact",
            "name": "Jimmy Doe",
            "@type": " IndividualParty"
        },

        {
            "id": "11",
            "href": "https://host:port/partyManagement/organization/11",
            "role": "Requester",
            "name": "Horizon LtD",
            "@type": " organizationParty"
        }

    ],
    "contactMedium": [
        {
            "preferred": true,
            "type": " TelephoneNumber ",
            "characteristic": [
                {
                    "phoneNumber": "04569885552"
                }
            ]
        }
    ],
    "quoteItem": [
        {
            "id": "1",
            "state": "In Progress ",
            "action": "add",

             "quantity": "15",
            "@type": "QuoteItem",
            "productOffering": {
                "id": "5295",
                "href": "https://host:port/productOffering/productOffering/5295",
                "name": "TMF Tariff plan ",
                "@type": "TMFTariffPlanPO"
            },
            "product": {
                "name": "TMF Tariff plan",
                "characteristic": [
                    [
                        {
                            "name": "Voice Bundle",
                            "value": "Illimited"
                        },
                        {
                            "name": "Data Bundle",
                            "value": "32 GB/month"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "2489",
                    "name": "RTMFPlan"
                }
            }
        },

 

        {
            "id": "2",
            "state": " In Progress ",
            "action": "add",

             "quantity": "10",
            "@type": " QuoteItem...",
            "productOffering": {
                "id": "63",
                "name": "Nice Handset",
            },
            "product": {
                "name": "Nice Phone",
                "characteristic": [
                    [
                        {
                            "name": "Memory",
                            "value": "32"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "9",
                    "name": "NicePhone",
                }
            }
        },

 

        {
            "id": "3",
            "state": " In Progress ",
            "action": "add",
            "quantity": 1,
            "productOffering": {
                "id": "85",
                "href": "https://host:port/productOffering/productOffering/85",
                "name": "24/7/7 Support"
            },
            "product": {
                "name": "Silver Support",
                "characteristic": [
                    [
                        {
                            "name": "Time to respond",
                            "value": "4H"
                        }
                    ]
                ],
                "productSpecification": {
                    "id": "289",
                    "name": "Support"
                }
            }
        }
    ]
}
 

Delete quote

  DELETE /quote/{id}

Note: this operation is available only to ADMIN API users

Description

This operation deletes a quote entity.

 

Usage Samples

Here's an example of a request for deleting a Quote resource.


Request
 

DELETE /quoteManagement/quote/42

 


Response
 

204

 

 

API NOTIFICATIONS

For every single of operation on the entities use the following templates and provide sample REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.

Register listener

  POST /hub

Description

Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.

 


Request
 

POST /api/hub

Accept: application/json

 

{"callback": "http://in.listener.com"}
 


Response
 

201

Content-Type: application/json

Location: /api/hub/42

 

{"id":"42","callback":"http://in.listener.com","query":null}

 

 

Unregister listener

  DELETE /hub/{id}

Description

Clears the communication endpoint address that was set by creating the Hub..

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.


Request
 

DELETE /api/hub/42

Accept: application/json
 


Response
 

204

 

Publish Event to listener

  POST /client/listener

Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY refers to the data structure of the given notification type.


Request
 

POST /client/listener

Accept: application/json

 

{

    "event": {

                EVENT BODY

            },

    "eventType": "EVENT_TYPE"

}
 


Response
 

201

 

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design Guidelines.

 


Acknowledgements

 

Release History

 

Release Number

Date

Release led by:

Description

Release 1.0

15/04/2016

Pierre Gauthier
TM Forum
pgauthier@tmforum.org

 

First release of draft version of the document

Release 1.1

 

 

Updated for use in the Paris Spec Jam – and rebranded

Release 2.0

18/09/2017

Pierre Gauthier
TM Forum
pgauthier@tmforum.org

Mariano Belaunde
Orange
mariano.belaunde@orange.com

Generated from API Data Model..

+update to comply with API new pattern

+ AP 935 feedbacks

 

Contributors to Document

Mariano Belaunde

Orange

Ludovic Robert

Orange

Guillermo Martinez

Telefonica

Pierre Gauthier

TM Forum