Page tree

      Frameworx Specification

 

Service Qualification API REST Specification

 

 

 

 

 

 

 

 

      TMF645

      Release 16.0.1

      October 2016

 

 

 

 

 

Latest Update: Frameworx Release 16

TM Forum Approved

Version 2.0.2

IPR Mode: RAND

 

NOTICE

 

Copyright © TM Forum 2016. 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.

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify the TM FORUM Team Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this deliverable.

 

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this TM FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this TM FORUM Standards Final Deliverable. TM FORUM may include such claims on its website, but disclaims any obligation to do so.

 

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this TM FORUM Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on TM FORUM's procedures with respect to rights in any document or deliverable produced by a TM FORUM Collaboration Project Team can be found on the TM FORUM website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this TM FORUM Standards Final Deliverable, can be obtained from the TM FORUM Team Administrator. TM FORUM makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

 

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 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

Service qualification Resource

Product-Offering Qualification Resource

Event Models

API OPERATION TEMPLATES

GET /api/ serviceQualification/{ID}/?{filter_and attribute selection}

POST /api/ serviceQualification

POST /api/ productOfferingQualification

GET /api/ productOfferingQualification/{ID}/?{filter_and attribute selection}

API NOTIFICATIO N

REGISTER LISTENER POST /hub

UNREGISTER LISTENER DELETE hub/{id}

publish {EventTYPE} POST /listener

Acknowledgments

VERSION HISTORY

Release History

Contributors to Document

 

List of Tables

 

Table 1 Service Qualification field description

 

Introduction

Service Qualification API is One of Pre-Ordering Management API Family. Service Qualification API goal is to provide service availability at Customer location.

In the Open Digital Economy where multiple actors (SDPs, CSPs, …) may be involved with the delivery of an end-to-end service, those actors need to collaborate and interact with the customer as needed.

 

ServiceQualification API operation checks are modeled as requests:

- serviceQualification request checks technical eligibility (serviceQualification resource),

- productOfferingQualification request checks commercial Eligibility. (productOfferingQualification resource)

 

Change diagram Taka Action #1

Spell Check + Format Andreas  #2

 

 

serviceQualification task

          Check if a location (identified by address) is within the service footprint (i.e. within a serving area)  and the type of service technology available at the location (i.e. access technology like Fiber, Wireless or Interim Satellite but also sensor data feed or utility service, HDTV availability), where detail response indicates technical parameters of service (e.g. bandwidth, data feed interval and accuracy, pipe diameter for water, etc).

          Intended for use cases where the “middle B [1] ” (retail ISP, reseller, etc) is not concerned about the product offering, but only about the service parameters.

          Allows for asynchronous responses via notification hub for checks that take longer.

          Should allow for serviceQualificationRequest for all types of services in a generic way, not only communication service access. If a telecom is sent a serviceQualificationRequest  it will respond with the network access technology and parameters available at the location. If an electricity supplier is sent a request, it will respond with the options on electritity (volts?) available at the location, when a water utility is sent a request, it will respond with service parameters available at the location (pipe diameter, pressure, )

productOfferingQualification task

          Check if a given product offering can be delivered to a specific location (identified by address).

          Provide available product offering options if a specific product is not requested/given Synchronous responses only

          Is about product offering level eligibility, where the “middle B” (reseller, etc) is not primarily concerned about technical parameters, but about product offering availability at location.

Depending on the way to describe “Product “, it may be classified in either technical feasibility or commercial feasibility. 

 

 

 

SAMPLE USE CASES

The following table maps out the use case s .

 

UC

description

1

A ‘new’ customer is browsing operator internet services webpage and wish to see which offers he is eligible with his current address. The system retrieves the list of offers technically eligible with characteristics and configuration .

1.1

Configuration could be detailed and for example the customer is informed that he is eligible for ADSL, TV online but he cannot have both TV HD and Multi-Screen TV options (just one of these ).

2

A ‘new’ customer is interested for FTTH service – he asks to SP sale representative about FTTH service at his current address. Thus system indicate he is eligible to FTTH and he will have a xx Mo/s speed for download and yy for upload.

2.2

Alternative: the address is ok for FTTH service but from a strictly technical point of view the operator FTTH center box have not enough space to plug a new connection. The Sale representative is able to inform the customer that he will be eligible to FTTH in 8 week

3

A customer wishes to enjoy HDTV. He asks to SP sale representative. He is eligible but he has to change his access offer.

3.1

Alternative: Access is ok but system checks that he is currently using an outdated TV decoder and he has to upgrade his TV box to enjoy HD.

4

A customer askes for TV on internet. An eligibility check is triggered and should check not only the TV channel provided by the SP but also the additionally TV channels availability at the customer address (even if they not directly provided by the SP).

5

A customer is moving to a new address – a check must be done at this new address and the SP sale representative is able to inform the customer if:

          he will be able to keep current offer at his new address

          he should downgrade his services because current ones are not technically feasible at the new address

          he can keep but also he is eligible to an upgrade and benefit for example to a FTTH broadband at his new address.

6

A TV channel provider wants to sell a set of channel for a customer. He will ask for the customer broadband company [API provider] and an access id (email address for example). He will use this information with this POST /serviceQualificationRequest api to be able to retrieve information on customer access capabilities (and check if the customer will be able to get his service from the service point).

7

A MVNO/other provider who use provider network will call this api to be able to check capabilities for one prospect. With this api he will have all technical information and he should have to apply his own commercial rules to make a proposal to this customer.
This UC could be a mandatory one for contractual reason where network is still owned by legacy Telco Company but they have to open it for competitors.

8

this api could be used in internal channel to be able to check technical capabilities without any commercial filter. It could be useful in some customer support UC.

9

A customer wishes to enjoy different products over multiple accesses. For example: HD TV, internet by fiber and phone service on ADSL. Customer is interested on the commercial offering and not on technical aspects so she calls to a sales representative for that.

 

 

RESOURCE MODEL

Managed Entity and Task Resource Models

Service Qualification API has 2 Resources

serviceQualification Task resource for knowing the allowed services based on specific criterions such as location, access network id and service properties

productOfferingQualification Task resource for knowing the product offering based on specific criterions such as location, related party and product offering properties

Service or product qualification tasks have a qualificationState . This is the state of the qualification request. Here is the state machine diagram for a qualification. Each qualification states are described in the tab below.

qualification State

Significance

InProgress

The qualification is progressing– the supplier has not yet make the qualification request. The qualification is in progress until all the information had been collected.

Done

The qualification has been done and the result is available in the qualification resource. The qualification is done if all the information had been collected successfully.

Terminated withError

The qualification has been done but there are some errors and result could be incomplete. The qualification is TerminatedWithError if all the information had not been collected successfully or if any other conditions preventing the execution of the tasks occurs.

 

Service qualification Resource

 

4 Examples of the JSON representation of Service Qualification :

For Service Qualification at a specific location 1 of Address ID, Address description, geoCode and publicKey should be provided.

 

You can provide an address conformant with the Address API Resource.

 

If you work with the address as below you can either provide the {id,href}, the address description (all properties except id href and geocode), or just the geocode.

 

Either Address or PublicKey.

 

{

  "id": "7660828",

  "href": "addresses/7660828",

  "streetNr": "225",

  "streetNrSuffix": "B",

  "streetNrLast": "",

  "streetNrLastSuffix": "",

  "streetName": "Strathmore",

  "streetType": "Terrace",

  "streetSuffix": "",

  "postcode": "5004",

  "locality": "Brighton",

  "city": "Brighton",

  "stateOrProvince": "SA",

  "country": "Australia",

  "geoCode": {

       "latitude": "1.430937",

       "longitude": "43.597208",

       "geographicDatum": "WGS84"

  }

}

 

1)       Address id for location info

2)       Address discription for location info

3)       Geocode for location info

4)       Public-key for location info

 

Service provider execute service qualification request with location information to get technical eligibility that is network access speed, available service list.

 

1)       ServiceQualification with Address id for location info

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
    "address" : {
        "id" : "12345678" ,
        "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666"
    } ,
    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,
        { "accessType" : "Fiber" }
    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

2)      Address discription for location info

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
    "address" : {
        "streetNr" : "1" ,
        "streetName" : "ville Marie" ,
        "city" : "montreal" ,
        "stateOrProvince" : "Quebec" ,
        "country" : "Canada "
    } ,
    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,
        { "accessType" : "Fiber" }
    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

3)       Geocode for location info

 

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification request" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
        "address" : {

      "geocode" : {
        "latitude" : "73.6393962" ,
        "longitude" : "45.5014452"
    } } ,
    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,
        { "accessType" : "Fiber" }
    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

 

4)       Public-key for location info

 

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification request" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
    "publicKey" : "public-Key_ 00000000" ,
    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,
        { "accessType" : "Fiber" }
    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
        {
            "service" : {
                "id" : "string" ,
                "href" : "string" ,
                "name" : "string" ,
                "serviceCharacteristic" : [{
                    "name" : "string" ,
                    "value" : "string"
                }] ,
                "serviceSpecification" : {
                    "id" : "2222" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "TVservice" ,
                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

 

Fields Description

Table Need to be updated Ludovic ?

ServiceQualification

Field

Description

i d

Unique identifier for Interaction.

eligibilityDate

The Date requested eligibility

a ddress

 

t ype

T ype of place

t d

Unique identifier for Place

h ref

Reference of a place (for instance in google map)

address description

Address description

streetNr

number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses

streetNrSuffix

the first street number suffix

streetName

the name of the street or other street type

streetType

alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf ?

streetSuffix

A modifier denoting a relative direction

c ity

the City that the address is in

locality

"An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi rural in nature." [ANZLIC-STREET], or a suburb "a bounded locality within a city, town or shire principally of urban character " [ANZLIC-STREET]

postcode

A descriptor for a postal delivery area, used to speed and simplify the delivery of mail

stateOrProvince

the State or Province that the address is in

country

the Country that the address is in

geoCode

Geographic code

latitude

Latitude

l ongitude

Longitude

geographicDatum

Geocoding referential

publicKey

a landline number or an internet access id

serviceSpecification

Requested service specification

i d

Unique identifier for serviceSpecification

serviceCharacteristic

 

i d

Servicecharactristic for  requested service

v alue

serviceCharacteristic value for requested service

serviceCategory

 

i d

Unique identifier for serviceCategory

provideAlternative

if this flag I set to Yes - the API will retrieve closest value available for this same service

provideOnlyEligible

used to restrict API response to only available services .

If this flag is set to No the API will provide both positive and negative eligibility results.

terminationError

if qualification has not been done properly we indicate there termination error

id

 

value

Unique identifier for terminationError

 

 

Field

Description

i d

Unique identifier for Interaction.

eligibilityDate

 

address

 

type

T ype of place

i d

Unique identifier for Place

href

Reference of a place (for instance in google map)

publicKey

a landline number or an internet access id

physicalResource

Array of physical resource for multiple access NW

physicalTerminationPoint

Logical resource for multiple access NW

accessType

Access Technology Type : ADSL, VDSL, fiber

serviceSpecification

Service specification for qualification service

i d

Unique identifier for Service specification

serviceCategoryId

Category id for requested service

serviceSpecificationCharacteristic

Characteristic for requested service

i d

Unique identifier for

value

 

serviceQualification

services with a specific eligibility check will be listed there with technical eligibility result

qualificationResult

Technical eligibility result:  service availability status which explain below

comment

Comment for technical eligibility result

qualificationResultDate

qualification judgement date

terminationError

if qualification has not been done properly we indicate there termination error

id

Unique identifier for terminationError

value

 

Table 1 Service Qualification field description

 

Serviceability status may be represented the following table.

 

 

serviceable-shortfall is include updating access NW.

substatus are captured via notation i.e  serviceable.existing etc…

In the case that the service provider or broker responding to the request already knows about an upcoming change in the serviceability status, it is intended that the response is sent as a collection of the about results, listing both the current and the future valid response with its state and a matching eligibility date. 

Product-Offering Qualification Resource

 

Example of the JSON representation of Product-Offering Qualification :

Service provider execute Product-Offering Qualification task to get the customer location Feasibility include Commercial and Technical eligibility.

{
    "id" : "42" ,
    "href" : "http::..//productOfferingQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
    "productInventoryId" : "ADSL_locate_No" ,
    "provideOnlyAvailable" : "No" ,
    "provideUnavailabilityReason" : "Yes" ,
    "partyId" : "service_provider_0001" ,
    "channel" : "web store" ,
    "address" : { "id" : "12345678" } ,
    "productOfferingQualificationItem" : [
        {
            "productOffering" : {
                "id" : "42" ,
                "href" : "http: //serverlocation: port/catalogManagement/productOffering/42" ,
                "category" : { "id" : "TVservice with Internet Play" } ,
                "product" : {
                    "productSpecification" : {
                        "id" : "13" ,
                        "href" : "http://serverlocation:port/catalogManagement/productSpecification/13" ,
                        "version" : "2.0" ,
                        "name" : "specification product 1"
                    } ,
                    "productCharacteristic" : [{
                        "id" : "downstreamspeed" ,
                        "value" : "10MBPS"
                    }]
                }
            } ,
            "orderFeasibilityCheck" : { "eligibilityResult" : "available" }
        } ,
        {
            "productOffering" : {
                "id" : "42" ,
                "href" : "http: //serverlocation: port/catalogManagement/productOffering/42" ,
                "category" : { "id" : "TVservice with Internet Play" } ,
                "product" : {
                    "productSpecification" : {
                        "id" : "13" ,
                        "href" : "http://serverlocation:port/catalogManagement/productSpecification/13" ,
                        "version" : "2.0" ,
                        "name" : "specification product 1"
                    } ,
                    "productCharacteristic" : [{
                        "id" : "downstreamspeed" ,
                        "value" : "6MBPS"
                    }]
                }
            } ,
            "orderFeasibilityCheck" : {
                "eligibilityResult" : "unavailable" ,
                "eligibilityUnavailablityReason" : [{
                    "code" : "UNAVAILABLE-300" ,
                    "label" : "need more bandwidth"
                }]
            }
        }
    ]
}
 

 

For each resource in your model fill the following table.

 

Fields Description

ProductOffering Qualification

 

Field

Description

partyId

Unique identifier for party

channel

Channel

productInventoryId

Product Inventory ID for commercial eli gi bility

address

 

id

Unique identifier for Place

href

Reference of a place (for instance in google map)

address description

Address description

streetNr

number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses

streetNrSuffix

the first street number suffix

streetName

the name of the street or other street type

streetType

alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf ?

streetSuffix

A modifier denoting a relative direction

city

the C ity that the address is in

locality

"An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi rural in nature." [ANZLIC-STREET], or a suburb "a bounded locality within a city, town or shire principally of urban character " [ANZLIC-STREET]

postcode

A descriptor for a postal delivery area, used to speed and simplify the delivery of mail

stateOrProvince

the State or Province that the address is in

country

the Country that the address is in

geoCode

Geographic code

latitude

Latitude

l ongitude

Longitude

geographicDatum

Geocoding referential

publicKey

a landline number or an internet access id

productOfferingSpecification

Requested product-offering specification

id

Unique identifier of product-offering specification

productOfferingCategory

Requested product-offering category

id

Unique identifier of product-offering category

productOfferingCharacteristic

A characteristic quality or distinctive feature of a product-Offering

id

Unique identifier of productOfferingCharacteristic

value

 

provideOnlyAvailable

If this flag is set to No the API will provide both positive and negative availability results.

provideUnavailabilityReason

add in the API the rational for not-authorized productOffering. The rationales for non-authorized are described in the eligibilityUnvailabilityReason structure in the response.

 

 

 

 

Field

Description

productOfferingSpecification

 

i d

ID of the top level productOffering

productOfferingCategoryId

Unique identifier for productOfferingCategory

productCharacteristic

 

id

Unique identifier for productCharacteristic

value

The value for productCharacteristic in this productOffering

orderFeasibilityCheck

Commercial and Technical eligibility result for this offer:

eligibilityResult

Eligibility result for this offer

eligibilityUnavailabilityReason

reason for eligibility result if the offer was unavailable

code

Unavailable reason code

label

Unavailable reason label

terminationError

if qualification has not been done properly we indicate there termination error

id

Unique identifier for termination error

value

 

 

 

For each resource in the API provide a UML model:

 

Figure 1 Service Qualification resource model TAKA do update to reflect real

 

Event Models

 

The Service Qualification API supports a single event called QualificationStateChange Notification. This event is used to track the qualificationState of a service or product offering qualification.

{
    "event" : {
       
    "id" : "42" ,
    "href" : "http::..//productOfferingQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "Done" ,
    "productInventoryId" : "ADSL_locate_No" ,
    "provideOnlyAvailable" : "No" ,
    "provideUnavailabilityReason" : "Yes" ,
    "partyId" : "service provider A" ,
    "channel" : "web store" ,
    "address" : { "id" : "12345678" } ,
    "productOfferingQualificationItem" : [{
        "productOffering" : {
            "id" : "42" ,
            "href" : "http: //serverlocation: port/catalogManagement/productOffering/42" ,
            "category" : { "id" : "TVservice with Internet Play" } ,
            "product" : {
                "productSpecification" : {
                    "id" : "13" ,
                    "href" : "http://serverlocation:port/catalogManagement/productSpecification/13" ,
                    "version" : "2.0" ,
                    "name" : "TVservice with Internet Play"
                } ,
                "productCharacteristic" : [
                    {
                        "id" : "upstreamspeed" ,
                        "value" : "1 MBPS"
                    } ,
                    {
                        "id" : "downstreamspeed" ,
                        "value" : "6 MBPS"
                    }
                ]
            }
        } ,
        "orderFeasibilityCheck" : { "eligibilityResult" : "available" }
    }]
}

}

    } ,
    "eventType" : "QualificationStateChange"
}

 

 

 

 

 

 

 

 

 

  API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST requests and responses.

Remember that the following Uniform Contract rules must be used:

 

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.

 

GET /api/ serviceQualification /{ID}/ ?{filter_ and attribute selection }

Description :

This operation is used to retrieve current serviceQualification tasks.

GET operation use if location id is created at other API/system.

 

 

Behavior :

  • Return status codes
    • 200 OK – the request was successful
    • 400 Bad Request – error, for example to cover these functional error cases:
      • Location is not exist

 

 

REQUEST

GET /api/serviceQualification/42

Accept: application/json

 

RESPONSE

200

Content-Type: application/json

 

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "Done" ,
    "address" : {
        "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666"
    } ,

    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,

    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "serviceCharacteristic" : [{
                    "name" : " upstreamSpeed " ,
                    "value" : "15KBPS"
                }] ,
                "serviceSpecification" : {
                    "id" : "ADSL" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "internetService" ,
                },

                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
 


            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

 

 

 

 

 

 

POST /api/ serviceQualification

Description :

This operation creates a Task to provide technical Eligibility that is what service is available or when the service is available.

Partner used this API to notice service availability Partner’s customer.

POST operation use if location id is create at this operation.

 

Attribute name

Mandatory

Default

Rule

Id

N

Blank

1.1.1.1.1      Should not be filled in the request. This Id is provided by the API supplier

eligibilityDate

N

Today

1.1.1.1.2      Date when the service eligibility should be checked

Address

N

 

Address info need one from any address representations

Address description

N

 

Address info need one from any address representations

geoCode

N

 

Address info need one from any address representations

publicKey

N

 

publicKey is used to identify network access point where the serviceQualification has to be done

serviceSpecification

N

 

serviceSpecification is used to restrict eligibility check to only thi(these) serviceSpecification(s)

serviceCharacteristic

N

 

used to specify minimum characteristic value to be assessed – example: Internet access with a download speed at least equals to 20 Mb/s.

serviceCategory

N

 

same as serviceSpecification but with specificCategory: restrict the scope of the assessed service (only those of this category)

provideAlternative

N

“No”

if this flag I set to Yes - the API will retrieve closest value available for this same service

Example: requester ask for a broadband access with a download speed at least equals to 20 Mb/s – if only 12 M/bs is available and provideAlternative is set to Yes, the API will provide this alternative information (20 Mb/s not available but 12 is)

provideOnlyEligible

N

“Yes”

If this flag is set to No the API will provide both positive and negative eligibility results

 

Behavior :

  • Return status codes
    • 201 OK – the request was successful
    • 400 Bad Request – error, for example to cover these functional error cases:
      • Location is not exist

 

Use case :

3 Examples for a Specific Service

          with Location

          with Location and Physical Characteristics

          with Service Specification and Characteristics

 

We assume requests are synchronous (i.e. responses are sent synchronously)

 

1) Can a service be provided at a specific location with the specified characteristics?

 

REQUEST

POST /api/serviceQualification

Accept: application/json

 

{

  “ address ” : {

    “href” : “https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666”

},

"provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "example of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,

"serviceQualificationItem" : [
        {
            "service" : {
                "serviceCharacteristic" : [{
                    "name" : " upstreamSpeed " ,
                    "value" : "15KBPS"
                }] ,
                "serviceSpecification" : {
                    "id" : "ADSL" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "internetService" ,
                }
            } ,
        } ]
 

 

 

}

RESPONSE

 

201

Content-Type: application/json

 

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "Done" ,
    "address" : {
        "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666"
    } ,

    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,

    ] ,
    "serviceQualificationItem" : [
        {
            "service" : {
                "serviceCharacteristic" : [{
                    "name" : " upstreamSpeed " ,
                    "value" : "15KBPS"
                }] ,
                "serviceSpecification" : {
                    "id" : "ADSL" ,
                    "href" : "https://serviceSpecification/ADSL" ,
                    "serviceCategoryId" : "internetService" ,

                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : "1MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "100KBPS" ,
                            "valueto" : "6MBPS"
                        }
                    ]
 


                }
            } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

2 ) can the access NW be provided at a specific location

REQUEST

POST /api/serviceQualificationRequest

Accept: application/json

 

{
    "id" : "42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "Yes" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
     "address" : { "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666" } ,
    "serviceQualificationItem" : [{ "service" : {
        "serviceCharacteristic" : [{
            "name" : "downstreamspeed" ,
            "value" : "10 Mbps"
        }] ,
        "serviceSpecification" : {
            " id" : " FiberAccess " ,
            "href" : "http://serviceSpecification/FiberAccess" ,
            "serviceCategoryId" : "FiberAccess"
        }
    }}]
}
 

RESPONSE

201

Content-Type: application/json

 

{
    "id" : "42" ,
    "href" : "http::..//serviceQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "Yes" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "InProgress" ,
    "address" : { "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666" } ,
    "serviceQualificationItem" : [{
        "service" : {

            "serviceSpecification" : {
                " id" : "2233" ,
                "href" : "http://serviceSpecification/FiberAccess" ,
                "serviceCategoryId" : "FiberAccess" ,
                },


        } ,

         "alternativeService" [

           “service” {
            "serviceCharacteristic" : [{
                "name" : "downstreamspeed" ,
                "value" : "5 Mbps"
            }] ,
            "serviceSpecification" : {
                " id" : "2233" ,
                "href" : "http://serviceSpecification/FiberAccess" ,
                "serviceCategoryId" : "FiberAccess" ,

                    "serviceSpecificationCharacteristic" : [
                        {
                            "id" : "2211" ,
                            "name" : "upstreamSpeed" ,
                            "valuefrom" : "10KBPS" ,
                            "valueto" : ".5MBPS"
                        } ,
                        {
                            "id" : "2212" ,
                            "name" : "downstreamSpeed" ,
                            "valuefrom" : "50KBPS" ,
                            "valueto" : "3MBPS"
                        }
                    ]
 


                }
        }] ,

       
        "availability" : "available-shortfall" ,
        "serviceabilityDate" : "20160201 10:00"
    }]
}

 

 

3) can the specific service be provided at a specific location (asking for specific characteristics but not specific service type (no specification is provided DSL or Fiber)

 

REQUEST

POST /api/serviceQualification

Accept: application/json

 

{
    "id" : "42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "address" : { "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666" } ,
    "serviceQualificationItem" : [{ "service" : { "serviceCharacteristic" : [
        {
            "name" : "upstreamSpeed" ,
            "value" : "1Mbps"
        } ,
        {
            "name" : "downstreamSpeed" ,
            "value" : "100Mbps"
        }
    ]}}]
}

RESPONSE

201

Content-Type: application/json

 

{
    "id" : "42" ,
    "interactionDate" : "20160201 10:00" ,
    "provideAlternative" : "No" ,
    "provideOnlyEligible" : "Yes" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "physicalTerminationPoint" : [
        { "accessType" : "ADSL" } ,
        { "accessType" : "Fiber" }
    ] ,
    "address" : { "href" : "https://www.google.ca/maps/dir/''/google+map+montreal+place+ville+marie/@45.5014452,-73.6393962,12z/data=!3m1!4b1!4m8!4m7!1m0!1m5!1m1!1s0x4cc91a4498f8f3db:0xa2760b4a779d61d3!2m2!1d-73.5693564!2d45.5014666" } ,
    "serviceQualificationItem" : [
        {
            "service" : {

{ "serviceCharacteristic" : [
        {
            "name" : "upstreamSpeed" ,
            "value" : "1Mbps"
        } ,
        {
            "name" : "downstreamSpeed" ,
            "value" : "100Mbps"
        }
    ],

 

"serviceSpecification" : {
                "id" : "ADSL" ,
                "href" : "https://serviceSpecification/ADSL" ,
                "serviceCategoryId" : "internetService" ,
            }} ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        } ,
        {
            "service" : { "serviceSpecification" : {
                "id" : "FiberService" ,
                "href" : "https://serviceSpecification/FiberService" ,
                "serviceCategoryId" : "Fiber"
            }} ,
            "availability" : "available" ,
            "serviceabilityDate" : "20160201 10:00"
        }
    ]
}

 

 

 

Description :

This operation is used to provide commercial eligibility from interaction contextual information (addresses, parties, channel) immediately.

  i.e Product Offerings (and constraints on ProductOffering pricing).

This operation execute for offering check.

Attribute name

Mandatory

Default

Rule

Id

N

Blank

Should not be filled in the request. This Id is provided by the API supplier

eligibilityDate

N

Today

Date when the productOffering eligibility should be checked

RelatedParty

N

 

1.1.1.1.3      Used to perform specific commercial eligibility based on party properties: specific productOffering are only sold through specific retaillers, specific productOfferings are only available for specific customers.

channel

N

 

1.1.1.1.4      Used to filter productOffering available only for this channel (e.g offering only available on web channel)

productInventoryId

N

 

If a productInventoryID is provided the API will provide only productOfferings compatible with this product.

address

N

 

the address is used to retrieve productOffering only available at this place

Address description

N

 

same as above

geoCode

N

 

same as above

publicKey

N

 

same as productInventoryID -> used to retrieve compatible productOffering to customer already owned products (and identified through this public key)

productOfferingSpecification

N

 

used to filter eligibility to this/these productOfferingSpecification(s)

productOfferingCategory

N

 

same a previous: restrict API scope to a productOfferingCategory

productCharacteristic

N

 

used to specify characteristic for assessed productOferings

provideOnlyAvailable

N

“Yes”

If this flag is set to No the API will provide both positive and negative eligibility results

provideUnavailabilityReason

N

“No”

This flag is used to add the rational for not-authorized productOffering.

 

Behavior :

  • Return status codes
    • 201 OK – the request was successful
    • 400 Bad Request – error, for example to cover these functional error cases:
      • Location does not exist

Use case :

Following example is to check commercial eligibility.

Request asks “what product can run through specific service provider”.

 

REQUEST

POST  /api/productOfferingQualification

Accept: application/json

Content-Type: application/json

 

 

{

    "provideOnlyAvailable" : "No" ,
    "provideUnavailabilityReason" : "Yes" ,
  "channel" : "web store" ,
 

    "product" :  {

      “id” : “ADSL_locate_No-#42”,

      “href” :  “http../////inventory/ ADSL_locate_No-#42”

    }
    "relatedParty":[

 

      {

 

         "role":"customer",

 

         "id":"345221",

 

         "href":"http://serverlocation:port/partyManagement/customer/345221",

 

         "name":"John Doe"

 

      },

 

      {

 

         "role":"csp",

 

         "id":"4563",

 

         "href":"http://serverlocation:port/partnerManagement/partner/4563"

"name":"x service provider"

 

 

      }

 

   ],     "address" : { "id" : "12345678" } ,
    "productOfferingQualificationItem" : [

{ "productOffering" : { "category" : { "id" : "TV Service with Internet play" }}}]
}

RESPONSE

201

Content-Type: application/json

 

{
    "id" : "42" ,
    "href" : "http::..//productOfferingQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "Done" ,
    "product" :  {

      “id” : “ADSL_locate_No-#42”,

      “href” :  “http../////inventory/ ADSL_locate_No-#42”

    } ,

"relatedParty":[

 

      {

 

         "role":"customer",

 

         "id":"345221",

 

         "href":"http://serverlocation:port/partyManagement/customer/345221",

 

         "name":"John Doe"

 

      },

 

      {

 

         "role":"csp",

 

         "id":"4563",

 

         "href":"http://serverlocation:port/partnerManagement/partner/4563"

"name":"x service provider"

 

 

      }


    "provideOnlyAvailable" : "No" ,
    "provideUnavailabilityReason" : "Yes" ,
    "channel" : "web store" ,
    "address" : { "id" : "12345678" } ,
    "productOfferingQualificationItem" : [{
        "productOffering" : {
            "id" : "42" ,
            "href" : "http: //serverlocation: port/catalogManagement/productOffering/42" ,
            "category" : { "id" : "TVservice with Internet Play" } ,
            "product" : {
                "productSpecification" : {
                    "id" : "13" ,
                    "href" : "http://serverlocation:port/catalogManagement/productSpecification/13" ,
                    "version" : "2.0" ,
                    "name" : "TVservice with Internet Play"
                } ,
                "productCharacteristic" : [
                    {
                        "id" : "upstreamspeed" ,
                        "value" : "1 MBPS"
                    } ,
                    {
                        "id" : "downstreamspeed" ,
                        "value" : "6 MBPS"
                    }
                ]
            }
        } ,
        "orderFeasibilityCheck" : { "eligibilityResult" : "available" }
    }]
}

 

 

Description :

This operation is used to retrieve current serviceQualification tasks.

GET operation use if location id is created at other API/system.

 

Behavior :

  • Return status codes
    • 200 OK – the request was successful
    • 400 Bad Request – error, for example to cover these functional error cases:
      • Location is not exist

 

Use case :

Following example is to check commercial eligibility.

Request asks “can these product run through specific service provider”.

 

REQUEST

GET /api/productOfferingQualification/42

Accept: application/json

 

RESPONSE

200

Content-Type: application/json

 

{
    "id" : "42" ,
    "href" : "http::..//productOfferingQualification/42" ,
    "interactionDate" : "20160201 10:00" ,
    "description" : "exmple of a qualification task" ,
    "eligibilityDate" : "20160201 10:00" ,
    "qualificationState" : "Done" ,
    "product" :  {

      “id” : “ADSL_locate_No-#42”,

      “href” :  “http../////inventory/ ADSL_locate_No-#42”

    } ,

"relatedParty":[

 

      {

 

         "role":"customer",

 

         "id":"345221",

 

         "href":"http://serverlocation:port/partyManagement/customer/345221",

 

         "name":"John Doe"

 

      },

 

      {

 

         "role":"csp",

 

         "id":"4563",

 

         "href":"http://serverlocation:port/partnerManagement/partner/4563"

"name":"x service provider"

 

 

      }


    "provideOnlyAvailable" : "No" ,
    "provideUnavailabilityReason" : "Yes" ,
    "channel" : "web store" ,
    "address" : { "id" : "12345678" } ,
    "productOfferingQualificationItem" : [{
        "productOffering" : {
            "id" : "42" ,
            "href" : "http: //serverlocation: port/catalogManagement/productOffering/42" ,
            "category" : { "id" : "TVservice with Internet Play" } ,
            "product" : {
                "productSpecification" : {
                    "id" : "13" ,
                    "href" : "http://serverlocation:port/catalogManagement/productSpecification/13" ,
                    "version" : "2.0" ,
                    "name" : "TVservice with Internet Play"
                } ,
                "productCharacteristic" : [
                    {
                        "id" : "upstreamspeed" ,
                        "value" : "1 MBPS"
                    } ,
                    {
                        "id" : "downstreamspeed" ,
                        "value" : "6 MBPS"
                    }
                ]
            }
        } ,
        "orderFeasibilityCheck" : { "eligibilityResult" : "available" }
    }]
}

 

 

API NOTIFICATIO N

 

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.

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.

REQUEST

DELETE /api/hub/{id}

Accept: application/json

 

RESPONSE

204

 

 

publish {EventTYPE} POST /listener

Description:

Provide the Event description

Behavior:

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

REQUEST

POST /client/listener

Accept: application/json

 

{
   
    "event" : {

    EVENT BODY
            } ,
    "eventType" : "eventType"
}

 

 

 


Acknowledgments

VERSION HISTORY

Version Number

Date

Modified by

Description

Version 1.0.0

15/04/2016

Pierre Gauthier

TM Forum

Final version

Version 1.0.1

17/06/2016

Alicja Kawecki

TM Forum

Updated cover; minor formatting/style corrections prior to publishing for Fx16

Version 2.0.0

15/05/2016

Pierre Gauthier

TM Forum

Updates for Fx16

Version 2.0.1

17/06/2016

Alicja Kawecki

TM Forum

Updated cover; formatting/style corrections prior to publishing for Fx16

Version 2.0.2

04/10/2016

Alicja Kawecki

TM Forum

Updated cover and Notice to reflect TM Forum Approved status

 

 

Release History

 

Release Number

Date

Release led by:

Description

Release 1.0

04/15/2013

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.

 

Contributors to Documen t

This document was prepared by members of the TM Forum API Program team.

 


[1] middle B as in B2B2X business scenarios, cf TM Forum B2B2X Partnering Guidebook