Open APIs

Expand all | Collapse all

TMF701 - clarification on API surface area

  • 1.  TMF701 - clarification on API surface area

    TM Forum Member
    Posted 13 days ago
    Hi

    I'm looking at TMF701 as a possible option to providing guided experience for users. In terms of the ODA model this is in the engagement management space.
    Today we have a config driven mechanism which isn't full BPMN. What it does (like BPMN) is define the archetype experience with all possible permutations (lots of decision forks) as XML.
    Then at runtime we create an instance of the flow that is unique to the user, recording which steps they take through the process. We drive this via some hypermedia. It works but is a bit clunky and we'd like to move to more TMF alignment.

    Having read TMF701 now what I just want clarified are a few points -
    - The API operations on ProcessFlow  such as GET/search - Is that defining the ability to access the design time archetype process definitions as resources, or is that finding runtime instances of process executions relevant for the client (perhaps based on their role/identity). I rather think the spec implies the latter.
    - But if this API allows manipulation of instance resources, I don't see an equivalent API set that allows for management of the process definitions, e.g. create/modify/publish/retire/search. Crucially how would a client know to find a process definition from which they create an instance. I see processFlowType as a field but I might want to query what all possible values of that are
    - Assuming for a moment the process API returns me an instance, I think then the task items can reflect what is the next available task step to perform, perhaps all the previous closed steps, but it need not show all possible tasks in the process, some of which aren't reachable in the current instance - right? I suppose the same is true of the taskflows?
    - Was there a reason why the API doesn't model process concepts like decision/fork/join/sub-process etc - too much overlap or coupling with implementations? As a result then the actionable/open tasks returned I think can only be essentially those which reflect possible next step in the instance.

    thanks

    ------------------------------
    Tim Fulcher
    ------------------------------


  • 2.  RE: TMF701 - clarification on API surface area

    TM Forum Member
    Posted 13 days ago
    Hello Tim,

    Regarding your first 2 points:
    The TMF701 intent is to manage runtime instance of ProcessFlow and instance of TaskFlow. This API is not designed to manage a 'ProcessFlowSpecification' (design time description of a Process Flow and Taskflow specification). We have the plan to deliver a specific API to manage the processFlow specification (It should TMF719 Process Flow Orchestration - the name is still subject to change). If you have the chance to browse last TMF Team action week I did a presentation to introduce this API.

    Regarding your third point it depends on your implementation. For example, in our implementation we leveraged some hypermedia capability to provide to client side at each step the list of task but also the current task(s) to be performed and the previous task(s) editable.
    An example - here we're in the middle of a processFlow running. The Front end sent ProductOffering Identity data and this is the response from the server:

    {
      "id": "8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8",
      "href": "http://apiServer/oda-catalog/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow/8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8",
      "correlationId": null,
      "completionMethod": null,
      "isMandatory": null,
      "priority": 50,
      "taskFlowSpecification": "description",
      "channel": [],
      "characteristic": [
        {
          "name": "DefineProductOfferingIdentityData",
          "id": null,
          "valueType": "Object",
          "@baseType": null,
          "@schemaLocation": null,
          "@type": "ObjectCharacteristic",
          "value": {
            "brand": "Orange",
            "name": "5GbyOrange",
            "description": "5G Mobile access",
            "isInstallable": true
          }
        }
      ],
      "relatedEntity": [],
      "relatedParty": [],
      "state": "active",
      "taskFlowRelationship": null,
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "TaskFlow",
      "_links": {
        "self": {
          "href": "http://apiServer/oda-catalog/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow/8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8"
        },
        "taskFlowList": {
          "href": "http://apiServer/oda-catalog/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow"
        },
        "nextTaskstoBePerformed": [
          {
            "title": "ProductOfferingCreation.defCategory",
            "href": "https://apiServer/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow/5ebbe9e0-29df-475b-9406-a45476d11ece",
            "state": "active",
            "taskFlowSpecificationId": "5ebbe9e0-29df-475b-9406-a45476d11ece",
            "taskFlowSpecificationCharacteristic": [
              {
                "name": "DefineProductOfferingCategory",
                "id": "5ebbe9e0-29df-475b-9406-a45476d11ece-DefineProductOfferingCategory-0",
                "valueType": "List",
                "minCardinality": 0,
                "maxCardinality": 1,
                "characteristicValueSpecification": [
                  {
                    "@type": "ObjectCharacteristicValueSpecification",
                    "isDefault": null,
                    "value": {
                      "DefineProductOfferingCategory": {
                        "required": ["productCategoryId"],
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "productCategoryId": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                ]
              }
            ],
            "method": "PATCH",
            "accepts": "merge-json-patch"
          },
          {
            "title": "ProductOfferingCreation.cancel",
            "href": "https://apiServer/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow/847e9260-aa3c-4eb5-9dea-80778a4090e9",
            "state": "active",
            "taskFlowSpecificationId": "847e9260-aa3c-4eb5-9dea-80778a4090e9",
            "taskFlowSpecificationCharacteristic": [
              {
                "name": "CancelEntityOperation",
                "id": "847e9260-aa3c-4eb5-9dea-80778a4090e9-CancelEntityOperation-0",
                "valueType": "Object",
                "minCardinality": 1,
                "maxCardinality": 1,
                "characteristicValueSpecification": [
                  {
                    "@type": "ObjectCharacteristicValueSpecification",
                    "isDefault": null,
                    "value": {
                      "CancelEntityOperation": {
                        "required": ["isCancelled"],
                        "type": "object",
                        "properties": {
                          "isCancelled": { "type": "boolean", "default": true }
                        }
                      }
                    }
                  }
                ]
              }
            ],
            "method": "PATCH",
            "accepts": "merge-json-patch"
          }
        ],
        "existingTaskEditable": [
          {
            "title": "ProductOfferingCreation.description",
            "href": "https://apiServer/catalog-configurator/processManagement/v4/processFlow/2a72cfdd-64d8-427e-a858-0c61f7b76ec8/taskFlow/8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8",
            "state": "active",
            "taskFlowSpecificationId": "8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8",
            "taskFlowSpecificationCharacteristic": [
              {
                "name": "DefineProductOfferingIdentityData",
                "id": "8c2fe2c5-738a-4a2e-9b87-e0a3acf9fed8-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"
          }
        ]
      }
    }
    ​

    It's a bit long but if you look afer the _links (before it is a standard PATCH response representation) you'll find:
    • a self on the task itself
    • a link to get a list of all task for this processFlow
    • a detail of the next task to be done (nextTasksToBePerformed) - this is the tasks that client side has to care about
    • and last, the task already completed that are editable (existingTaskEditable).
    At last for your fourth point - yes for now we stick to a simple approach and not bring too much complexity for now. This is something that we can challenge un future.

    Hope it helps

    Ludovic


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



  • 3.  RE: TMF701 - clarification on API surface area

    TM Forum Member
    Posted 7 days ago
    Ludovic

    OK thanks for your reply, I think it's a bit clearer now.
    So to play back for a moment, in our use case a customer online aims to complete a process which conceptually has 4 phases. In each phase there's essentially a multi-step wizard, some phases have an arbitrary number of steps (dictated at runtime).  Should I model that as a process of 4 taskflows, each taskflow having I guess a task with a taskrelationship akin to 'next', so no absolute need to list task/relationships to those tasks which I've not yet reached (nor might I be able to reach).
    Likewise, I could model a taskrelationship of 'back' or 'previous' should a customer want to reverse back a couple of steps and alter details.
    I presume a taskflow instance in itself is never best to be more than 1 logical form/screen (though I guess nothing stops it being so).
    But if that's the case then how would I delineate when 1 phase of the process ends, i.e. I move between taskflows - perhaps they just have different taskflowspecification names?

    Lastly, does the spec have a view on error/exception handling in process/taskflow? Do we model a taskFlow in the process that might always be the next step under an error condition?

    Tim

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