Open APIs

Expand all | Collapse all

Understanding TMF 633 (how to declare simple service specification)

  • 1.  Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 21, 2020 08:08

    Hi,

    I'm new to TM Forum and evaluate how to revamp in house SOM application based on TMF 633/TMF 641/ TMF 638.

    I read TMF633 Service catalog management API REST specification (release 18.5.0/pp21, 27-29) but I have no glue how to declare/represent simple (key value) service specification.


    For simple/standalone service spec without any service dependency, should I declare everything in ServiceSpecification/ServiceSpecCharacteristic/ServiceSpecCharacteristicValue?

    Regards



    ------------------------------
    Wai Chow
    PCCW Solutions Limited
    ------------------------------


  • 2.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 21, 2020 08:20
    Hi Wai

    Welcome, hope you will find your interaction with the TM Forum productive for yourself and your company.

    All the published Open API user guides (we used to call them specifications) include examples of JSON resources and payloads. As the Open API team continue to work on API definitions, we try to refine and update the examples so that they will reflect real business scenarios, as far as possible.

    Indeed the simplest way to define a service in the catalog is to use completely dynamic definitions, with specifications, specificationcharacteristics, and values. An example below (admittedly from Resource Catalog, but the idea is very similar for Service Catalog) for a very simple spec for a storage with one characteristic for the maximum storage, using values to represent the list of allowed values.

    Hope it helps.

    {

        "name": "Virtual Storage Medium",

        "description": "This resource specification defines the virtual storage medium",

        "@type": "LogicalResourceSpecification",

        "@baseType": "ResourceSpecification",

        "resourceSpecCharacteristic": [

            {

                "name": "Maximum Allowed Storage",

                "description": "The storage limit in the virtual storage medium, ",

                "valueType": "integer",

                "configurable": true,

                "minCardinality": 1,

                "maxCardinality": 1,

                "isUnique": true,

                "resourceSpecCharacteristicValue": [

                    {

                        "valueType": "integer",

                        "value": 1024000

                    },

                    {

                        "valueType": "integer",

                        "value": 2048000

                    }

                ]

            }

        ]

    }



    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 23, 2020 04:15
    Hi Jonathan,

    Thanks for your clarification.
    If I need to create <voice mail service> with three operations/actions, should I create
    • 1 <voice mail> service catalog
    • 3 service catalog (<add voice mail>, <delete voice mail>, <update voice mail>)?

    eg/

    {
      "name""ADDVMS",
      "description""Add Voice Mail Service Specification",
      "isBundle"true,
      "lastUpdate""2020-07-22T02:47:10.141Z",
      "lifecycleStatus""Active",
      "version""0.1",
      "serviceSpecCharacteristic": [
        {
          "configurable"true,
          "name""MSISDN",
          "description""Mobile Number",
          "extensible"true,
          "isUnique"true,
          "maxCardinality"1,
          "minCardinality"1,
          "valueType""string"
        },
        {
          "configurable"true,
          "name""IMSI",
          "description""IMSI Number",
          "extensible"true,
          "isUnique"true,
          "maxCardinality"1,
          "minCardinality"1,
          "valueType""string"
        },
        {
          "configurable"true,
          "name""BRANDCODE",
          "description""Brand (mapping)",
          "extensible"true,
          "isUnique"true,
          "maxCardinality"1,
          "minCardinality"1,
          "valueType""string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault"true,
          "valueType""String"
              "value": "0"
            },
            {
              "isDefault"false,
          "valueType""String"
              "value": "1"
            }
          ]
        },
        {
          "configurable"true,
          "name""VMSSERVICECLASS",
          "description""Mail Box Type",
          "extensible"true,
          "isUnique"true,
          "maxCardinality"1,
          "minCardinality"1,
          "regex""",
          "valueType""string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault"true,
          "valueType""String"
              "value": "3"
            },
            {
              "isDefault"false,
          "valueType""String"
              "value": "5"
            }
          ]
        },
        {
          "configurable"true,
          "name""VMSLANG",
          "description""Mail Box Language (mapping)",
          "extensible"true,
          "isUnique"true,
          "maxCardinality"1,
          "minCardinality"1,
          "regex""",
          "valueType""string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault"false,
          "valueType""String"
              "value": "1"
            },
            {
              "isDefault"true,
          "valueType""String"
              "value": "2"
            },
            {
              "isDefault"false,
          "valueType""String"
              "value": "3"
            }
          ]
        }
      ],
      "@type""CustomerFacingServiceSpecification"
    }

    Thanks

    ------------------------------
    wai chow
    PCCW Solutions Limited
    ------------------------------



  • 4.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 23, 2020 06:21
    Hi Wai
    The service catalog definition reflects the service, not the operations that you carry out on the service. You should create a single Voice Mail service specification in the catalog.
    To add, change, or remove voice-mail, you would presumably need to process a service order TMF641 - or perhaps if you can work directly against the network you could use service activation and configuration TMF640.
    Specific comments on your proposed model:
    • The Open API model does not distinguish between CFS and RFS - if you want to make that distinction that's fine, but then you need to include a @baseType that contains ServiceSpecification and a @schemaLocation that defines CFS extension to ServiceSpec.
    • I think it would be better to have true values in your characteristic examples, so that someone who looks at the spec (and the instantiation in the inventory) can understand the semantic meaning. Values such as "3" and "5" for serviceclass, or "1" and "2" for national language, are not necessarily helpful.
    • If you set isBundle to true, the expectation is that the service spec has sub-structure, and I would expect to see a reference to a contained service spec.
    Hope it helps​​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 5.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 27, 2020 01:36
    While it's true that "the Open API model does not distinguish between CFS and RFS" explicitly it does so implicitly by the inclusion of resourceSpecification in an RFS.

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------



  • 6.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 27, 2020 03:54
    Hi Jonathan,

    My main purpose is to define specification (CFS) for north bound/COM.
    Then, our middleware (SOM) should translate/decompose TMF 641 order and then invoke RFS service logic.  I don't want north bound/COM to invoke the RFS/ TMF640 directly.

    So I will perform these 2 activities.
    1. Define service catalog (TMF 633) without any operation carry out on the service.
    2. Define order spec (TMF 640) with operations carry out on the service

    Am I on the right track?

    Seems TMF 633 itself without any operation carry out on the service does not have too much value at all, do I misunderstand the rationale behind TMF633?

    Thanks

    ------------------------------
    wai chow
    PCCW Solutions Limited
    ------------------------------



  • 7.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 27, 2020 07:10
    TMF633 is a catalog API, representing the functionality of defining services and their capabilities.
    TMF640 is one of a family of instance APIs in the service domain, representing functionality of acting on a specific service (in this case activating and configuring the service in the network). So TMF640 is not the place to expose the allowed actions.

    Subject to correction by domain experts such as @Vance Shipley and @Kamal Maghsoudlou, it seems to me that there is a tacit assumption that there is a fixed and closed list of actions you can take on a service, adding, modifying, suspending, resuming, and terminating. Perhaps you would like to see a more explicit list of actions defined at catalog level, since some services would not allow suspend or resume, others might not allow modify, etc.

    This concept is missing from the Open API catalog APIs (Product, Service, Resource); it is present in the Information Framework (SID) for Product in the Product Action ABE, but there is no SID equivalent for Service actions.

    So ​in an implementation of TMF640 API you might well reject a request to (for example) suspend a service, based on your internal knowledge of the service definition, even though this is not currently represented in catalog APIs.

    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 8.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 27, 2020 07:33
    Hi Jonathan,

    Thanks for your comments, I have updated the spec accordingly.
    However, I want to ask how can we include the semantic meaning in the spec? As we want the value pass as a value instead, would it be fine to add "description" tag as following? Or any better approach?

    Thanks.

          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
              "valueType": "String",
              "value": "3",
              "description": "Normal"
            },
            {
              "isDefault": false,
              "valueType": "String",
              "value": "5",
              "description": "Premium"
            }
          ]
    

    {
      "name": "VMS",
      "description": "Voice Mail Service Specification",
      "lastUpdate": "2020-07-22T02:47:10.141Z",
      "lifecycleStatus": "Active",
      "version": "0.1",
      "serviceSpecCharacteristic": [
        {
          "configurable": true,
          "name": "MSISDN",
          "description": "Mobile Number",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string"
        },
        {
          "configurable": true,
          "name": "IMSI",
          "description": "Mobile SIM Number",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string"
        },
        {
          "configurable": true,
          "name": "BRANDCODE",
          "description": "Brand",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "0"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "1"
            }
          ]
        },
        {
          "configurable": true,
          "name": "VMSSERVICECLASS",
          "description": "Mail Box Type",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "regex": "",
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "3"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "5"
            }
          ]
        },
        {
          "configurable": true,
          "name": "VMSLANG",
          "description": "Mail Box Language",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "regex": "",
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "1"
            },
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "2"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "3"
            }
          ]
        }
      ]
    }


    ------------------------------
    Wing Sin
    PCCW Solutions Limited
    ------------------------------



  • 9.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Jul 28, 2020 11:41
    Hi Wing
    I think you raised something similar in another post, regarding mapping between an internal (numeric) characteristic value in RFS and an external (human-semantic) value in CFS.
    At any rate the Open API does not have any distinction (currently, at any rate) between a value and some human-readable representation of that value. This is true for characteristics and for values in strongly-typed enums.
    I guess that the idea is that the Open API deals with backend integration, and is not concerned with presentation issues.
    You can of course extend the model and API by adding attributes, perhaps "displayValue" would be clearer than "description", if that is your intention.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 10.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Aug 25, 2020 07:57
    Hi Jonathan,

    Thanks for your comments, I have updated the spec.
    Would you please advise if we could include the semantic meaning with "description" tag as we want to pass those value instead. Or is there any better approach?  Thanks.
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
              "valueType": "String",
              "description": "Normal",
              "value": "3"
            },
            {
              "isDefault": false,
              "valueType": "String",
              "description": "Premium",
              "value": "5"
            }
          ]
    
    {
      "id": "1",
      "name": "VMS",
      "description": "Voice Mail Service Specification",
      "lastUpdate": "2020-07-22T02:47:10.141Z",
      "lifecycleStatus": "Active",
      "version": "0.1",
      "serviceSpecCharacteristic": [
        {
          "configurable": true,
          "name": "MSISDN",
          "description": "Mobile Number",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string"
        },
        {
          "configurable": true,
          "name": "IMSI",
          "description": "Mobile SIM Number",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string"
        },
        {
          "configurable": true,
          "name": "BRANDCODE",
          "description": "Brand",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "0"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "1"
            }
          ]
        },
        {
          "configurable": true,
          "name": "VMSSERVICECLASS",
          "description": "Mail Box Type",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "regex": "",
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "3"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "5"
            }
          ]
        },
        {
          "configurable": true,
          "name": "VMSLANG",
          "description": "Mail Box Language",
          "extensible": true,
          "isUnique": true,
          "maxCardinality": 1,
          "minCardinality": 1,
          "regex": "",
          "valueType": "string",
          "serviceSpecCharacteristicValue": [
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "1"
            },
            {
              "isDefault": true,
    		  "valueType": "String",
              "value": "2"
            },
            {
              "isDefault": false,
    		  "valueType": "String",
              "value": "3"
            }
          ]
        }
      ]
    }


    ------------------------------
    ----------------------------------
    Wing Sin
    PCCW Solutions Limited
    ----------------------------------
    ------------------------------



  • 11.  RE: Understanding TMF 633 (how to declare simple service specification)

    TM Forum Member
    Posted Aug 26, 2020 01:46
    Hi Wing

    To my non-practiced eye your example looks OK.
    I already stated my recommendation, which is that if you are in any case extending CharacteristicValueSpecification then "displayValue" seems to me a better name than "description".

    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------