Open APIs

 View Only

  • 1.  TMF701 TaskFlow characteristic

    Posted Aug 18, 2021 10:01
    Hi,

    Request your help with an issue around defining characteristic.
    We were looking at TMF701 for modelling a process flow and have a query around how to model a task flow with multiple characteristics. As per the swagger spec (given below), we can use @baseType and @schemaLocation to qualify the value under characteristic. But we have 2 scenarios that require support of multiple characteristics.
    1. Different tasks will have different characteristics. For e.g. Task 1 could have a shopping cart characteristic, Task 2 would have payment details under characteristic and Task 3 will have address details. When defining the swagger spec, if the type is defined as ObjectCharacteristic, is there a way to state that the object could be any of the defined types - shoppingCart, paymentDetails or addressDetails. And if so, how do I link multiple type locations under schemaLocation. We tried this using anyOf (as defined in swagger spec) but when we use openApiGenerate, it creates a single object which has properties for all the 3 objects.
    2. Single task could have two different characteristics where both are different objects. Again couldn't find a way to define this in a strongly typed manner

    Is there a clean way of defining the above 2 scenarios please.

    Relevant extract of characteristic spec
                   "value": {
                    "$ref": "#/definitions/Any",
                    "description": "The value of the characteristic"
                },
                "@baseType": {
                    "type": "string",
                    "description": "When sub-classing, this defines the super-class"
                },
                "@schemaLocation": {
                    "type": "string",
                    "format": "uri",
                    "description": "A URI to a JSON-Schema file that defines additional attributes and relationships"
                },
                "@type": {
                    "type": "string",
                    "description": "When sub-classing, this defines the sub-class entity name"
                }

    Thanks, 
    Lakshmi
    ​​​​

    ------------------------------
    Lakshmi Pillay
    Tech Mahindra Limited
    ------------------------------


  • 2.  RE: TMF701 TaskFlow characteristic

    Posted Aug 19, 2021 04:47
    Hello Lakshmi

    We had same challenge in our implementation where we want to manage 'complex' characteristic for TaskFlow. 

    We took a different approach than yours and we came to the conclusion to manage TaskFlowSpecification (Design time)where we can define the expected characteristic structure for a task.

    For example, suppose a task need the user to fill product offering data (name, brand, description, isInstallable) , the taskFlowSpecification will define them:
    "taskFlowSpecificationId": "4987b9c2-7188-4f47-973d-f1c3b8362156",
                "taskFlowSpecificationCharacteristic": [
                    {
                        "name": "DefineProductOfferingIdentityData",
                        "id": "4987b9c2-7188-4f47-973d-f1c3b8362156-DefineProductOfferingIdentityData-0",
                        "valueType": "Object",
                        "minCardinality": 1,
                        "maxCardinality": 1,
                        "characteristicValueSpecification": [
                            {
                                "@type": "ObjectCharacteristicValueSpecification",
                                "isDefault": null,
                                "value": {
                                    "DefineProductOfferingIdentityData": {
                                        "required": [
                                            "name",
                                            "description"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "brand": {
                                                "type": "string"
                                            },
                                            "description": {
                                                "type": "string"
                                            },
                                            "isInstallable": {
                                                "type": "boolean",
                                                "default": true
                                            }
                                        }
                                    }
                                }
                            }
                        ]​

    Then runtime, when the process is executed we provide to the system in charge of the task completion (the front end) this data in _links

    Here is an extract from the POST ProcessFlow response where in the _links part the next task is described

    {
    ....
    "_links": {
        "self": {
            "href": "http://.../processManagement/v4/processFlow/5319685f-9623-4692-a8ba-c2b0f38b4c31"
        },
        "taskFlowList": {
            "href": "http://g..../processManagement/v4/processFlow/5319685f-9623-4692-a8ba-c2b0f38b4c31/taskFlow"
        },
        "nextTaskstoBePerformed": [
            {
                "title": "ProductOfferingCreation.description",
                "href": "https://.../processManagement/v4/processFlow/5319685f-9623-4692-a8ba-c2b0f38b4c31/taskFlow/4987b9c2-7188-4f47-973d-f1c3b8362156",
                "state": "active",
                "taskFlowSpecificationId": "4987b9c2-7188-4f47-973d-f1c3b8362156",
                "taskFlowSpecificationCharacteristic": [
                    {
                        "name": "DefineProductOfferingIdentityData",
                        "id": "4987b9c2-7188-4f47-973d-f1c3b8362156-DefineProductOfferingIdentityData-0",
                        "valueType": "Object",
                        "minCardinality": 1,
                        "maxCardinality": 1,
                        "characteristicValueSpecification": [
                            {
                                "@type": "ObjectCharacteristicValueSpecification",
                                "isDefault": null,
                                "value": {
                                    "DefineProductOfferingIdentityData": {
                                        "required": [
                                            "name",
                                            "description"
                                        ],
                                        "type": "object",
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "brand": {
                                                "type": "string"
                                            },
                                            "description": {
                                                "type": "string"
                                            },
                                            "isInstallable": {
                                                "type": "boolean",
                                                "default": true
                                            }
                                        }
                                    }
                                }
                            }
                        ]
                    }
                ],
                "method": "PATCH",
                "accepts": "merge-json-patch"
            },
....
        ],
        "existingTaskEditable": []
    }
}​


    Then, once the user complete task in the front, the front end just pass the valued characteristic:
    PATCH http:.../processManagement/v4/processFlow/5319685f-9623-4692-a8ba-c2b0f38b4c31/taskFlow/4987b9c2-7188-4f47-973d-f1c3b8362156

{
    "characteristic": [
        {
            "name": "DefineProductOfferingIdentityData",
            "value": {
                "brand": "Orang",
                "name": "5GbyOrange",
                "description": "5G Mobile access",
                "isInstallable": true
            },
            "valueType": "Object",
            "@type": "ObjectCharacteristic"
        }
    ]
}​


    As I wrote previously, this is a different approach than yours but hope it can provide you some 'food for thought'

    I've plan to contribute this requirement for ProcessFlowSpecification and TaskFlowSpecification to TMF

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 3.  RE: TMF701 TaskFlow characteristic

    Posted Aug 19, 2021 07:22
    Ludovic

    Thanks for the reply. I work with Lakshmi and this in turn overlaps with a query I posted a while back. Just so I'm clear on what you are suggesting, at design time we could define a 'palette' if you like of prototype tasks that a client can expect to receive within a process, each with their own characteristic specification. At runtime you indicate which spec is being presented with an according reference, thereby side stepping any need to declare a list of possible types/specs? 
    The thing is, that sounds a lot like the principles behind HATEOAS where runtime discoverability is assumed. In reality, we've found that especially in the front end development community that brings some complexity which they feel is unwelcome; instead they prefer to know well in advance (i.e. design time) what payloads they have to build against. As such is there a middle ground whereby a form of metadata API exists where all possible task specifications can be retrieved ahead of time, and outside of a process flow?

    Tim

    ------------------------------
    tim fulcher
    ------------------------------

    Original Message


  • 4.  RE: TMF701 TaskFlow characteristic

    Posted Aug 19, 2021 10:12
    Hello Tim,

    I understood the requirement from the front end developers to not discover 'on the fly' the data structure to be captured. This is a fair & valid point.
    For me, it is a good rationale to provide ProcessFlowSpecification & TaskFlowSpecification resources, isn't it?

    These are defined design time. In the definition of the TaskFlowSpecification we find this description of the data to be captured. So this exists and Front End could be coded accordingly (Front End did not discover task on the fly).
    Then in design time, in a TaskFlow completion request, the TaskFlowSpecification identifier is passed. In the response that taskFlow data are passed as characteristic. In this case this is very similar to the management of the characteristicSpecification/characteristic  for product.

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------

    Original Message


  • 5.  RE: TMF701 TaskFlow characteristic

    Posted Aug 19, 2021 08:54
    Hi Lakshmi,

    Is it possible to share your swagger specs  the generated source.

    Thanks,
    Hanumantha M
    OpenAPI Enthusiast.

    ------------------------------
    Hanumantha Marikanti
    Saralam Technologies
    ------------------------------



Related Content