Open APIs

 View Only
  • 1.  TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Dec 21, 2021 12:15
    hi,

    I'm designing a fulfillment process where the orchestrator is sending a creation WO request.
    In the current swagger i need to send a mandatory parameter - WorkOrderItem.
    This complex structure specifies the Id and action as mandatory attributes.
    My question are:
    1. The WorkOrderItem Id is expected to be generated by the client?
    2.  WorkOrderItem has a workSpecification parameter. its not mandatory but i have a discussion with colleagues on whether the client needs to send any information in there.
    My approach is to guarantee a decoupling of the orchestrator and the work force system and not send any work specifications. Orchestrator can send the required equipment, the location, the order action, but not the type of work that needs to be done.

    Interested to get your inputs.

    Meirav

    ------------------------------
    meirav gat sherman
    Amdocs Management Limited
    ------------------------------


  • 2.  RE: TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Dec 30, 2021 03:32
    Hello Meirav
    WorkOrder follow the same pattern as all order API.  The WorkOrder itself is some kind of header and each work requested are described in one WorkOrderItem. A workOrder could describe n requests for work (and so n WorkItems). The information at WorkOrder level are common for all WorkItem.
    1. Yes, it should be. The workOrderItem.id is an internal index of the item within this order. This id has only to be unique within the workOrder.
    2. The work specification is used to describe which work is requesting. For me, it is mandatory for a new work request else how you will specify what is expecting (unless it is implicit). The cardinality in the API is 0,1 to accommodate UC where an existing Work is in progress (like recurring work) and the workOrder/workorderItem is used to modify or terminate it (In this case the work.id is required).

    Hope it helps,
    Ludovic

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



  • 3.  RE: TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Dec 30, 2021 04:28
    Hi Ludovic,

    Thanks for you reply. i'd like to refer to it and state the issues that i am not fully clear on.
    You wrote:
    1. Yes, it should be. The workOrderItem.id is an internal index of the item within this order. This id has only to be unique within the workOrder.

    Meirav: So this is an internal indexing generated by me. i am cool with it.

    2. The work specification is used to describe which work is requesting. For me, it is mandatory for a new work request else how you will specify what is

    Meirav: i agree that i need to specify the work, but lets assume i want to install a terminal. so i surely need to send the location and the type of device/s. but these are sent in the under the order and 
    place parameters. what else is required in the WorkSpecificationRef? if i send an id and name of a specific WorkSpecification, is that my internal generated input? i assume not. and in that case it means that i need to hold a full  list of all the relevant work specifications that are mastered in the workforce mng system.
    I dont think its correct. Why?
    1. It is a duplication of information and what i see as an unnecessary coupling. When my workforce mng system will update its list of work specs, they will have to make sure i am aligned with them.
    2. i need to hold a mapping between between category ("install"), deviceType, deviceMake/model, and maybe more and the workspecification. It seems like the workforce mng system responsibility.

    I will be happy to discuss it further.
    Meirav



    ------------------------------
    meirav gat sherman
    Amdocs Management Limited
    ------------------------------



  • 4.  RE: TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Dec 30, 2021 10:58
    Hi Meirav
    I get your point: The work Specification is managed by the Workforce management, and it allows exposing the list of work "request-able". If you do not use it (and it is fair) you have to be sure to have a way to explicitly and consistently allow requester to specify the work expected.
    For your example, I guess the POST should be something like this:
    {
      "description": "Simplified Exemple of a workOrder",
      "externalId": "1236",
      "priority": "1",
      "requestedCompletionDate": "2022-01-04T15:30:23.367Z",
      "workOrderItem": [
        {
          "id": "1",
          "description": "Description of the first Work item",
          "action": "add",
          "work": {
            "description": "Install a new device",
            "place": [
              {
                "name": "Meirav's house",
                "role": "InstallationPlace"
              }
            ],
            "relatedParty": [
              {
                "name": "Meirav",
                "role": "Contact"
              }
            ],
            "workSpecification": {
              "id": "123",
              "name": "DeviceInstallation"
            }
          }
        }
      ]
    }​

    We can have another work specification for DeviceMaintenance or DeviceRepair, etc...
    By the way, I was not able to associate device in the request (resource in TMF wording).

    Probably, @Pierre Robitaille who lead this API work could provide additional feedbacks.

    Hope it helps
    Ludovic




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



  • 5.  RE: TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Jan 02, 2022 08:13
    Hi Ludovig,

    You raised an excellent point. The device/resource does not appear on the workorder structure.
    We have the installation place, related contact party, required action, and we really need the device.
    I thought that it can be retrieved from the related orderRef, but really, i think that the device needs to be added as an explicit attribute. I'm not sure that the BSS order holds the full device details at that point, so not sure this will work anyway.
    Let's hope @Pierre Robitaille will have additional information.

    Thanks, Meirav



    ------------------------------
    meirav gat sherman
    Amdocs Management Limited
    ------------------------------



  • 6.  RE: TMF697 - what is expected to be provided by the client in workOrderItem as part of creation of a new workOrder

    TM Forum Member
    Posted Jan 08, 2022 05:22

    Hi Ludovic,

    you wrote "The work specification is used to describe which work is requesting. For me, it is mandatory for a new work request..."

    In the SID the WorkOrderItem has a n-to-1 relationship to Workspecification and Work. In the API WorkOrderItem has no relationship to Workspec - Is that a gap in the API?

    When we want to issue a work order, we want to order the elementary WorkItems - described by "WorkSpecification" and later in the process of "1.5.5.7. Manage workorder" creating "work"-Tasks - but as far as I see in the API, we have to define "work" in the "WorkOrderItem" already - no chance to issue a Workorder without work in the API?

    But work is s.th. that we want to define after grouping the elementary WorkItems (defined by WorkOrderItems with WorkSpecificatin) to assignable "Work Tasks" (see eTom  1.5.5.5.2 Analyze and Decompose Work Order). 
    The idea is to order Work by WorkOrderItems that refer to Workspecification of "elementary Work Items". Then the Work (tasks) are created by grouping the Work Items to "WorkTasks".  To do this, the API should provide a possibility  to create a workOrderItem only with "WorkSpecification". 

    If we define WorkItems as WorkOrderItems (only) which refer to Work, we have many WorkOrderItems which define one Work. P.ex. a Technician has one WorkTask "home Access install" assigned and the Workitems are "Search Call to Customer", "switch the APL", "Install the CPE". 

    It might be possible to define the Request in that way, that the WorkItems refer to one Work by name - "home Access install" (like in your example "Install a new device").
    Or do is the idea that WorkOrderItem and Work are always 1-to-1 and we have to define "Work Item" as "work" refering "Work Task" as a kind of "compound" or "bundled" Work?



    ------------------------------
    Michael Wald
    Deutsche Telekom AG
    Certified TM Forum Open API Practitioner
    ------------------------------