Open APIs

Expand all | Collapse all

TMF701 and Camunda (BPMN) flows

  • 1.  TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 19, 2021 09:09
    Hi,

    we have developed several flows using Camunda to implement the ServiceOrderingManagement (TMF641) and ServiceActivationAndConfiguration (TMF640) logic. We basically have a SOM master flow that delegates processing of each serviceOrderItem.service to a ServiceActivation sub flow.

    we now decided to implement TMF701 and use the POST /ProcessFlow to do the flow instantiation (using the property processFlowSpecification to pass the camunda flow name) and if manual tasks are present to update the corresponding TaskFlow (using the corresponding PATCH) after the manual action (via a GUI for example) has been completed. These 2 operations doing the update in the DB and the corresponding action through REST in the Camunda Engine.

    we expected this API to be about that and also about tracking the tasks execution by Camunda (via TaskFlow): basically, a new TaskFlow would be created and attached to the ProcessFlow as tasks are executed in Camunda. However this does not seem to be what the API was designed for as there is no possibility to create new TaskFlow through the API.

    According to discussions in the forum and some hints in the API documentation as well, it seems the sequence of TaskFlow is supposed to be created during ProcessFlow instantiation (with "new" state) and then updated as the flow is being executed.

    Our issue is that, by definition, in BPMN flows are dynamic: they have branching and looping features.
    Even if we create all possible TaskFlow when creating a ProcessFlow (duplicating what is already designed in Camunda) using the isMandatory property to take somehow into account the branching/optional aspect of the flow execution. It would not support looping or the fact that a TaskFlow could be executed multiple times.

    How this API is supposed to take into account this non deterministic aspect of a flow execution?

    I saw discussion about a ProcessFlow catalog that could describe the ProcessFlow (and I guess the possible transitions between TaskFlow objects). If that is the case, it would conflict with designing the flow using the BPMN engine and its nice modeler GUI as you would have to design it 2 times...

    What are your view on how to use this API in relation to a BPMN engine?

    best regards,



    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------


  • 2.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 19, 2021 10:53
    Hello Frederic

    As you wrote it TMF701 exposes via a REST API a proces flow instance running on a bpmn engine like Camunda - or directly hard coded. We trigger a new instance of a process by using POST ProcessFlow.

    The point you're highlighed is about the TaskFlow 'creation' (generation). From my perspective taskFlows are not created outside the µservice exposing the API but within this µservice by running the event received (by event or by PATCH on taskFlow ). This is why when we delivered this API we did not provide this POST taskFlow operation (to avoid 'outside' taskFlow creation).
    I'm aligned with you about the dynamic flow and for me there is not issue to have a one time 2 tasks for this process and later 5. New tasks could be generated as the process is running (and that why using hypermedia stuff is very useful for this API).

    As the API leader for this API I'm very open to your feedback and particurlarly to get your rational/implementation feedback about adding a POST ProcessFlow/{id}/TaskFlow operation. If we separate in one hand the bpmn from, in the other hand, the component managing the API then - yes - probably the POST ProcessFlow/{id}/TaskFlow makes sense.

    On this ProcessFLow API topic we'll have a session on future TMF Team Action Week (probably Monday February 1st) about new ProcessFlowOrchestration API - This API will allow to manage the ProcessFlowSpecificatino & TaskFlowSpecification.

    Hope it helps

    Ludovic

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



  • 3.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 20, 2021 03:36
    Hi Ludovic,

    Thank you for your quick answer.

    In our particular implementation, we have a camunda ms that executes the Camunda engine and is injected with DB configuration, flow descriptions (bpmn files) and Spring beans that basically handle the tasks business logic. We would like to implement TMF701 as a facade ms for the camunda ms so applications that want to execute a flow would go through the API (at the moment our flows are 100% automatic but we intend to integrate UserTasks as well so the PATCH on Taskflow will come into handy). In the camunda ms we have a small framework that takes care of tracking task executions and create a sort of Step list stored in a camunda variable that can be retrieved at any moment in time to check the flow progress (very alike the TaskFlow sequence concept). Our idea was then to modify this framework to integrate calls to TMF 701 ms to create a TaskFlow instance instead of this Step concept. To do this, as we have 2 separate ms, we need a POST on TaskFlow.

    As I see the API, there is 2 different ways of using it but i'm not sure which one is the correct one:
    1) Generate the list of possible TaskFlows at flow instantiation (probably from some sort of catalog as it's not possible to pass the TaskFlows during the POST) and then when the flow executes, PATCH the TaskFlow state and maybe characteristics and relationships. In this case, how would you tackle the dynamic character of a ProcessFlow if you have 2 separate ms? Quite frankly, I don't see the point of this initial TaskFlow list as it will anyway probably change greatly during flow execution.
    2) Have an empty Taskflow list at flow instantiation (so no need for a catalog, simply rely on Camunda design) and as the flow executes, create a new TaskFlow each ime Camunda executes a Task (first ACTIVE and then COMPLETED/CANCELLED or HOLD if UserTask). In this case the ProcessFlow could be seen as a mean to track a flow execution (BPMN or other). This would support dynamic flow. The only issue is that there is no way to create new TaskFlow dynamically through the API. This solution is the one most compatible with our view on TMF701. To support the flow execution, our camunda ms is already calling our TMF 633/638/640/641 and other internal module ms.

    But I guess the first big question is which of the 2 approach is correct?

    Best regards,


    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 4.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 20, 2021 08:20
    Hi Frederic

    Your rationale makes sense. I will raise a Jira to add a POST processFlow/{id}/taskFlow operation for next release. If it's not a problem for you I would like to extract part of your post in the Jira explanation. Let me know if it's ok.

    Regarding the question ... seems to me that for your implementation, the pattern 2 is the best option. But I'm also thiniking that from a TMF API offering we must be able to support both pattern. Indeed if we manage a "serial" process without a bpmn engine - but hard coded - an approach with all tasks instantied with status could also ok. This is also why we have in mind to add a new API to manage ProcessFlow Specification (and taskFlow Specification)

    One last point...In our implementation we are making a distinction between the list of the tasks for a running processFlow from the list of the task that can be done at any time (where we use hypermedia pattern to expose nextTasks to be completed).

    Hope it helps
    Ludovic

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



  • 5.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 20, 2021 08:31
    Hi Ludovic,

    That's great news ;) Of course you can reuse parts of my message...

    Do you have an idea how this new POST operation will look like? I would like to add it in our copy of the TMF701 API yaml so that we can begin implementation asap ;)

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 6.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 20, 2021 10:21
    Frederic,

    We are going very fast on this one ....just got green light from the API gouverance for this JIRA - I will work on this shortly but I assume the POST request should be aligned with our pattern : use current representation less id and href attributes.  Usually we did not have the state in the request but in this context I'm wondering if we should not allow to specify the state  in the request - please provide feedback ;)

    Probably new release will be the 4.1 because we'll need also to integrate impact with the release of ProcessFlowOrchestration API (to add a clean reference to ProcessFlowSpecification & TaskFlowSpecification).

    Ludovic

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



  • 7.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 20, 2021 10:57
    Ludovic,

    I think state should be allowed in the POST. If not, the default state would be NEW which is not the state we want when creating a new TaskFlow from Camunda (which would be ACTIVE).

    On another note, i think that both ProcessFlow and TaskFlow are missing startDate/endDate properties. At the moment, only processFlowDate (set at flow creation) is available. I know we can still use characteristics for that but to be aligned with other TMF APIs like TMF638 where you have these dates as properties.

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 8.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 21, 2021 04:23
    Hi Frederic,

    About the date, first probably we may introduce a TaskFlowCreationDate to allow logging timestamp of the (sub)resource creation (no business meaning here). This is valued by server side. Standard pattern in our API.

    Second, we can add some 'business' date(s) but i'm wondering if we should not instead look for state change history.
    At minimum adding a expectedCompletionDate (a due date) will make sense.

    We'll have to go thru the Jira process for this again.

    Thanks

    Ludovic

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



  • 9.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 21, 2021 04:39
    Hi Ludovic,

    this state change history (with date) seems inetresting. Is it a new pattern you will generalize to all TMF Resources that have a state property (like TMF638/Service and TMF641/ServiceOrder)?

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 10.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 21, 2021 11:06
    Frederic
    This is a topic in our backlog that I hope we'll be able to tackle and add in TMF630 guideline soon.

    Ludovic

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



  • 11.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 22, 2021 04:11
    Hi Ludovic,

    Once the flow (especially if asynchronous) completes in Camunda (Success or Error), we need to be able to update the ProcessFlow through the API (at least to update the state) so I think a PATCH should also be possible on the ProcessFlow.

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 12.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 25, 2021 03:13
    Hello Frederic
    Yes make sense - Will add it in a new Jira (with expectedCompletionDate ).

    For your information we'll have a session next monday (Feb 1st) for the TMF Action week (virtual) about API ProcessFlow Orchestration (to manage ProcessFlowSpecification & TaskFlowSpecification) 18:00 - 19:30 CET .

    Ludovic

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



  • 13.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted Jan 26, 2021 04:01
    Hi Ludovic,

    I'm in the process of implementing the APi and an additional point came to mind. I would like to be able when retrieving (through list/retrieve) ProcessFlow(s) to be able to also get the details of the TaskFlows and not only the Ref. Don't you think the RefOrValue pattern should be applied to the taskFlow of a processFlow and similarly to the taskFlow of a TaskFlowRelationship on the TaskFlow resource?

    I have also a question regarding the state property. What state would you use to indicate a Process/TaskFlow in error?

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 14.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted 30 days ago
    Hello Frederic,

    For your UC I invite you to look on TMF630 Design Guideline document (part 2) and look for use of EXPAND and DEPTH directive. This seems to me the right recommendation for GET extension to ref.

    For the second question  if we have an error preventing nomimal Process/tack execution can we use Hold state ? this means that the process/task is not 'terminated' but need some 'fix'.

    Ludovic

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



  • 15.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted 30 days ago
    Hi Ludovic,

    yes we have implemented the depth/expand where the APIs support it (like for TMF638) but TMF701 does not support RefOrValue as the processFlow.taskFlow is a list of TaskFlowRef. If we want to have a list of TaskFlowRefOrValue, we would have to modify the API yaml so that the generated code would allow what we want. This would defeat the purpose of a Standard APi, wouldn't it ;) ?

    For the state questions, our flows are (at the moment) all automatic so if there is an error, the flow must stop (in a final state). To fix the error, support teams need to change documentation in possibly multiple legacy (at the moment) systems or correct the initial ServiceOrder. After that the order is retried or a new order is sent (both instantiating a new ProcessFlow/Camunda flow)... The support/human intervention side is not part of our flows because it's done by other teams (from possibly other branches of the company). The flows themselves only support our part/side of the provisioning chain...

    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------



  • 16.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted 29 days ago
    Frederic,
    First point is not easy.... you want to retrieve a list of ProcessFlow (so not a GET by id but a GET by list) and get for all of them the TaskFlow by value. This is good case for depth/expand but get your point about the generated code. I'm wondering id it's not a case where to leveraging some polymorphism and allow through the @type in TaskFlowRef to use extension - I mean define the @type as discriminator and depending if it's valued to 'TaskFlow' or 'TaskFlowRef' provide a distinct representation. Just a exploratory id.

    About second point I'm fine about adding a failed status but first we need to define what is the situation. If a process is failed - Does it means that the situation is clean and everything by the process before the error has been cancelled - or does it means that the situation is a 'mess' and some task has been completed but at least one is failed ? In you case how do you handle previous task compelted before the faile ?
    I'm wondering if we should not first add this failed stated only for task (process is hold if a task is a 'mandatory' is  failed).

    We are going in depth here and I'm wondering if we should not have a dedicated call on this topic within the TMF API team development call :)
    ​​
    Hope it helps

    Ludovic

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



  • 17.  RE: TMF701 and Camunda (BPMN) flows

    TM Forum Member
    Posted 29 days ago
    Ludovic,

    Regarding my first question, it's becoming a bit more "complicated" for me. I am nearly done with TMF701 implementation and camunda integration for our project and I'm starting to wonder why there are 2 separate resources in TMF701 and in particular why TaskFlow is a resource and not an entity attached to the ProcessFlow resource. According to the API, it seems a TaskFlow cannot exist without a ProcessFlow (all operations on TaskFlow requires a processFlowId in the url). Unless there is something I am missing, there could just be a ProcessFlow resource with a list of TaskFlowRefOrValue. Both ProcessFlow and TaskFlowRefOrValue would have links to Characteristic, RelatedEntity, RelatedParty and ChannelRef. TaskFlowRefOrValue would also have a list of TaskFlowRelationship that would link to a TaskFlowRefOrValue.
    That would support depth/expand and also make the data model more compact and, I think, more consistent with other TMF APIs...

    Regarding the state question, the situation can be anything. A rollback could have occurred and so the final situation would be clean or no rollback occurred, part of the work was done and the situation is "incomplete". In the later case, the new flow is supposed to detect what was already done and start from the failed step/task.


    Best regards,

    ------------------------------
    Frederic Thise
    Proximus SA
    ------------------------------