Open APIs

 View Only
  • 1.  TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Oct 28, 2022 05:04
    Hi Team,

    Looking to understand why there is discrepancy in the shipping order examples given in API spec vs Swagger?
    API Spec explains the shipping order create with "Product" and product specification details. Here, no SKU is mentioned. My interpretation is that the API provider (may be supplier) is must to have integration with or have inbuild product catalog to refer to SKU details.
    While API swagger, does provide example with Create ShippingOrder with shipmentItem object where SKU can be passed directly.

    Are these two patterns given explicitly for API implementers to choose the approach as per available resource and desired use cases? OR is there MUST to have product catalog solution in place (by Supplier) for shipping order creation?

    What is recommended approach out of these two - 
    1. Receive product details and specs in TMF700 POST
    2. Receive direct SKU under shipmentItem and keep the shipping order product/service agnostic.

    Can you please help with this.

    ------------------------------
    Pawan Makode
    [Amdocs Development Centre India Ltd]
    ------------------------------


  • 2.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Oct 31, 2022 05:33
    Hi Pawan,

    Thank you for bringing this up.
    The current TMF700 ShippingOrder API spec that uses Product is a violation of the separation of concerns principle.
    The same issue exists  with TMF687 Stock Management API.
    This issue is already mentioned in the IG1228 v11 and should eventually result in JIRA tickets for these API.

    The issue is not a simple one and will need detailed discussions.
    In my personal opinion this also means that there will be impact on the ResourceCatalog as well. SID has a StockItem ABE that is currently not used by any of the OpenAPI,
    I am currently preparing a contribution in this sense.

    Not everything is finailised but I appreciate comments on my line of thinking:

    Catalog view

    Assume the simple case of an ethernet switch being rented by as CPE.
    At the specification level this means that we can define a PhysicalResourceSpecification of type Equipment to represent an ethernet switch.
    At the next level we probably need to define further PhysicalResourceSpecification of type Port to represent  the ethernetPorts and another PhysicalResourceSpecification of type Auxiliary component to represent a power supply.

    The ethernetswitch would have relationships between the Ethernet switch and the EthernetPort and the power supply.
    Using current TMF can expose this ethernet switch in a resource catalog using a ResourceCandidate.
    In fact I will be exposing two diffferent models of ethernet switches. Model A has 8 ports and an integrated power supply. Model B has 24 ports and 2 replaceable power supplies. This indicates that the current model is lacking some important capabilities to express this situation.

    This means that in my resource catalog I want to see a ResourceCandidate for each of these models, linked to my single ResourceSpecification. For supply chain purposes each of these ResourceCandidates needs an embedded StockItem to indicate that I can use it in shippingOrders and stock Management. The stockItem has a code field for the GTIN code that is a standardised code for your SKU numbers. We also can extend the ResourceCandidate model so that it has the relationships to explain its composition. In such a model the ResourceCandidate for ou model Model A switch will have 8 'portOnDevice' relationships to ResourceCandidates for the ethernet ports. These ResourceCandidates can be named according to the nomenclature of the switch eth1, eth2, eth3, ... Since there is no supplychain for the ethernet ports these ResourceCandidates don't have an embedded stockItem. The same applies to the power supply of model A, but not to the power supply of Model B. Because the power supply of switch B can be ordered as a spare part, the resourceCandidate for this powersupply will have an embedded stockItem.

    The newly extended ResourceCandidate now serves already two purposes:
    • supply chain processes via the embedded stockItem
    • resource decomposition for the resource inventory
    Eventually the ResourceCandidate can be extended to serve even more purposes. Obvious extensions in my view are procurement cost and relationships to activities for installation processes.

    Stock Management View

    In resource model for the TMF687 stock management API will need to be realligned with SID StockItem ABE. It also will need to be adjusted to model where the ResourceCandidate is composed of StockItem and other concerns. Further consideratons will have to include serialised (e.g. ethernet switch) and non serialised resources (e.g. patchcord). That aspect is even not fully elaborated in the SID ABE.

    Shipping Order View

    Also here the resource model needs to be realigned with the SID StockItem ABE.

    ResourceOrder View

    A further analysis of the purpose of the resource Order seems required. On of its puposes is the maintenance of the resource inventory, including the decomposition of composite resources. But that obviously means the the TMF652 Resource Order will need to be extended to use ResourceCandidates, because that is the only way to communicate that switch model A has 8 ports and model B has 24 ports.

    Resource Inventory View

    The TMF639 Resource Inventory API currently doesn't support the ResourceCandidate and only refers to ResourceSpecification. Also here the model will need to be extended to included ResourceCandidates.

    We can conclude that the simple introduction of the SKU of GTIN is not a simple change only impacting one OpenAPI. The maturity of the resource domain will be dramatically improved by this exercise but it is a fairly substantial overhaul and will require time to implement.

    Regards





    ------------------------------
    Koen Peeters
    OryxGateway
    ------------------------------



  • 3.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    Posted Nov 08, 2022 06:11
    Hi Koen,

    Thanks for this interesting thread. I have a question on your statement "In fact I will be exposing two different models of ethernet switches. Model A has 8 ports and an integrated power supply. Model B has 24 ports and 2 replaceable power supplies. This indicates that the current model is lacking some important capabilities to express this situation." To which "lacking important capabilities" do you refer?

    Thanks and best regards,


    ------------------------------
    Roland Leners
    alvatross by SATEC
    ------------------------------



  • 4.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Nov 08, 2022 12:41
    Hi Roland,

    I have worked with the below extended ResourceCandidate.
    To support decomposition process:
    • The model is extended with an array of ResourceCandidateRelationships in order to drive a resource decomposition in a ResourceInventory.
    • The model is also extended with an array of ResourceCandidateCharacteristics so that characteristic that are static for the model can be set.
    To support SupplyChain processes:
    • The model is extended with a stockitem
    • The stockItem has plannedCosts
    • The Stockitem has terms (durations that can be used for planning)


    
    Below is an example of a ResourceSpecification for a ethernet switch
    {
    "@type": "ResourceSpecification",
    "name": "EthernetSwitch",
    "resourceSpecificationRelationship": [
    {
    "relationshipType": "portOnChassis",
    "@referedType": "ResourceSpecification",
    "name":"EthernetPort"
    }
    ]
    }
    With the extension a switch with 4 ports can be modeled that can be ordered in Supply Chain:
    {
    "@type": "ResourceCandidate",
    "name": "SwitchA",
    "resourceSpecification": {
    "name": "EthernetSwitch"
    },
    "stockItem": {
    "sku": "1234567890123",
    "codeModel": "EAN",
    "description": "Model A Ethernetswitch"
    },
    "resourceCandidateRelationship": [
    {
    "relationshipType": "portOnChassis",
    "@referedType": "ResourceCandidate",
    "name":"eth0"
    },
    {
    "relationshipType": "portOnChassis",
    "@referedType": "ResourceCandidate",
    "name":"eth1"
    },
    {
    "relationshipType": "portOnChassis",
    "@referedType": "ResourceCandidate",
    "name":"eth2"
    },
    {
    "relationshipType": "portOnChassis",
    "@referedType": "ResourceCandidate",
    "name":"eth3"
    }
    ]
    }

    I hope this clarifies how the model can be extended.

    ------------------------------
    Koen Peeters
    OryxGateway
    ------------------------------



  • 5.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Oct 31, 2022 07:10
    Edited by Matthieu Hattab Nov 01, 2022 10:00
    Hello,

    I don't have specific answers to your questions but some thoughts:
    • If we go one step back you have a Ressource Order (RO). The RO has a PhysicalResourceSpecification, which includes a charactheristic called SKUNumber and a value.
    • TMF700 has ShipmentItem sub-resource that also has the SKU and similar attributes (API Spec does mention SKU on page 30).
    OMS can therefore submit a request to create a Shipping order (the request already contain the SKU)  in the Logistics component.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 6.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Oct 31, 2022 08:15
    Hi,

    Thank you for the questions; however, I would like to tackle them individually.
    First of all, to understand what discrepancy we are talking about in the original question raised by @Pawan Makode.

    The TMF700 Shipping Order, as described in the model, exposes different models to cope as best as possible with the variety of configurations in all telco operators.
    As such, it provides the option to pass the Product Offering in the Shipping Order via the ProductOfferingRef. Now, depending on the ordering journey used by the telco operator, a product might be already instantiated in the product inventory, and hence the product information might be specified in the shipping order, hence the 'ProductRefOrValue' presence in the API specification. The shipping order needs at least one of these two pieces of information to be present to allow the logistic partner to proceed with the shipping.


    @Pawan Makode, your question was regarding the 'discrepancy' between the shipping order examples given in API spec vs Swagger.
    Although, I'm not clear on the discrepancy in scope here since the samples from within the API Documentation are health checked (validated) against the swagger definition by the tooling pipeline.
    Looking through the API Userguide for the "create" example, I can see the following snapshot:

    "shippingOrderItem": [
        {
          "id": "1",
          "action": "add",
          "productOrderItem": {
            "id": "1",
            "name": "Maker XPhone",
            "href": "https://host/tmf-api/productOrder/v4/productOrder/7800",
            "productOrderId": "7800"
          },
          "product": {
            "id": "100",
            "name": "Maker XPhone",
            "href": "https://host/tmf-api/productInventoryManagement/v4/product/100"
          },
          "productOffering": {
            "id": "4500",
            "name": "Maker XPhone",
            "href": "https://host/tmf-api/productCatalogManagement/v4/productOffering/4500"
          },
          "quantity": "1"
        }​


    In the above example, both sets of information (ProductOffering and Product) are passed along as they are not mutually exclusive. As demonstrated by the 'href' presented, one points to the ProductInventory (assuming the instance is already created in the inventory) and one to the ProductCatalog.
    The 'SKU' as in Stock Keeping Unit, was added to the ShippingOrder as a request from the community as it is useful/helpful by/to the logistic partner or shipment partner to update the Shipping Order Item information as the Shipping Order is progressing through its lifecycle.,

    Now, @Pawan Makode, you mentioned that the API Swagger does provide examples where SKU is provisioned as part of the create, however in the published Swagger, I can't find this case - can you point me to the TMForum asset where examples are provided inline with the swagger file?
    Or are we talking about the swagger editor, which will automatically generate an example for you but the payload examples that TMForum supplies are only coming in the form of the UserGuide?

    So, @Pawan Makode, my apologies for the long reply. The short answer was actually long, but I would say the options are there, and it is up to the implementation specific to decide which features and which integration path to use.

    Regarding the 'What is recommended approach out of these two' question, in my view, the OMS(POOM in the new terminology) most likely will not pass the SKU directly because it won't have the information available, but instead, it will pass the ProductOffering and if available Product details (saving another API call to the Product Catalog) depending on how the ordering journey has been modelled in the specific implementation. However, if some other sort of integration is available and it has the information available, then it can pass it, but I strongly recommend also passing the Product Offering and all the other order details.

    Now, to the second part to address @Koen Peeters's  concerns regarding using the 'ProductRefOrValue' and SID StockItem. The reference to the ProductRefOrValue was added to the specification as an optional path, based on the community request to address the difference in scenarios if the product is already instantiated in the inventory or not by the time of placing the shipping order.
    Regarding the second point, on the 'StockItem' topic.
    In my view, a shippingOrderItem is different from a StockItem - yes, there can eventually be a relationship between them, meaning a ShippingOrderItem can point to a StockItem.
    As part of the internal review process, the SID team also reviewed the ShippingOrder specification back in November and then again in February this year before going to the Beta table.

    I'm aware of the comments from the IG1228 V11 regarding the ShippingOrderItem and the StockItem. However, those will have to be clarified by the two working groups ODA and openAPI. I believe there is a misunderstanding of how the 'Shipment' has to be computed or what are the logistic partner steps in doing that - pretty much OMS or (POOM) doesn't need to do any special computation of the shipment (shipment or shipping orders will be computed by the logistic partners taking into account the customer requests or the warehouse/stock indications - meaning new shipments might be added in the order) - or at least what was the OpenAPI group scenarios collected during the analysis phase for the API but happy to take any feedback or contributions going forward to continue to improve the API in the next releases.

    Thank you,
    Florin


    ​​​​​

    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 7.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Nov 01, 2022 11:11

    Hi @Florin Tene,

    Thank you for elaborated response.
    My comments for few points as below:
    1. Discrepancy example: Yes, I was referring to ​example generated in swagger editor. Snippet below. It seems that this is not a valid example but the representation of all data objects of TMF700 model.


    The swagger may need to have specific examples for each API operations.

    2. Coming to main object of this "To refer product catalog ref or product instance ref" or "none of these"
    @Florin Tene, you recommend the product specification should be referred in the Shipping Order creation. How will this universally fit in a use case where "single product specification represents multiple SKUs". e.g., A productSpec (ProductOffering ) is of Mobile Device which can refer to Apple iPhones of multi colors, multi specs. Each distinct combination of color & memory size results in different SKU for same productSpec. Unless, product is instantiated (yet to be fulfilled to active state), the characteristics of productSpecRef may not specify the actual ordered SKU.
    So SKU or Bill of material Id (BOM ID), if product is bundle of shippable SKUs, either required to be passed as product characteristics as Product details.
    Supplier may not need to know a product offering what Telco is offering, but least mandatory dispatchable unit either BOM ID / SKU what is required for shipping.
    If you agree with this use case and example - should the recommended approach of API community is to use "Product" details or ShipmentItem?

    3. Use of ShipmentItem for order progression and notification
    If suppliers/parterns are expecting to publish the shipping order details, the order state change for specific shipping order item may be reflecting on the order item than shipmentItem. Unless, single shippingOrderItem requested with aggregated BOM ID which was decomposed and shipped into multiple SKUs. Each SKU represent individual shipmentItem and can be tracked separately. In this case, is order item status expected to represent aggregated status of all shipmentItems underneath it? Ae all shipmentItems (ideally) to be dispatched together - is this supplier/partners operational thinking? 

    As I mentioned in base query, I am looking a guidance on implementation approach to keep this API product/customer facing service/resource agnostic. If consumer applications know least orderable info for shipping i.e., SKU/BOM ID, is using ShipmentItem data object for ShippingOrder creation right approach? Or Does it violate any standard guideline principle?

    Appreciate your assistance on this. Apologies for another long questionnaire.

    ​​

    ------------------------------
    Pawan Makode
    [Amdocs Development Centre India Ltd]
    ------------------------------



  • 8.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Nov 01, 2022 12:35
    Edited by Florin Tene Nov 01, 2022 12:40
    Hi @Pawan Makode,

       No ​problem.
       Regarding point one, good, i thought you're looking in that space. To your point the new version of the APIs will leverage the example section going forward from V5.
       
       Regarding your second point:
     

    Let me provide some overview and high-level details about how the API is designed.

    The API (TMF700) ShippingOrder was designed to handle the orders at different granularities - we have a ShippingOrder and then we have Shipment(s) available as a resource via the ShipmentRefOrValue or via the separate API TMF711.

    ShippingOrder requests the LogisticPartner to handle the shipping of a set of ordered items, and then the LogisticPartner depending on the business processes or capabilities will create different shipments.

    A customer can place an order, which results in a shipping order.

    If in the order, all items follow the same shipping characteristics (shipping speed, address, places etc) then the logistic partner can create a single Shipment for them, otherwise, the same ShippingOrder will result in multiple shipments. 

    Now in terms of design, the ShippingOrder API follows the same pattern as ProductOrder API (TMF622), meaning it provides a reference to the ProductOrder as well as ProductRefOrValue entities. As part of the ProductRefOrValue entity, the ProductSpecification can provide all additional details required to identify the product. 

    Now back to your question.

    This is a very good point, but it goes back to my original reply; it depends on how all the other things are modelled and the context constraints. 

    What I mean by this is your scenario above is placing the implementation on a specific path, where you have in your catalogue a single ProductOffer which covers multiple configuration variations. More commonly, I would say, you will have a different ProductOffer (usually using inheritance capability from the ProductCatalog) for each combination as most likely they will result in different prices, tc's, etc but I agree this is very implementation specific.

    So, if this is the scenario where are in, then there are multiple options available in the current API specification:

    • If the OMS has the SKU available, then it can pass it directly as part of the Shipment entity and pass the SKU as part of the 'ShipmentItem' entity as mentioned by @Matthieu in the previous post.

    • Another alternative is that it can pass all characteristics as part of the ShippingOrder -> ShippingOrderItem-> ShipmentRefOrValue->ShipmentItem->ProductRefOrValue->ProductSpecification, and the logistic partner can compute the exact SKU (I believe this is the most common case - where the Logistic Partner will receive either a ProductOffering or a ProductRefOrValue)
    • Another alternative is for the LogisticPartner to compute the SKU based on the ShippingOrder->ShippingOrderItem->ProductOrderItemRef (this will involve another call in the ProductOrder to retrieve the ProductRefOrValue which contains the ProductSpecification).

    Regarding your question, "should the recommended approach of API community is to use "Product" details or ShipmentItem?" - i think we are mixing two different things. 

    The ShipmentRefOrValue and ShipmentItem will always be required as each ShippingOrder can result in one or multiple shipments but it will always have at least one.

    It depends on the system's capabilities to implement the ShippingOrder (e.g. logistic partner).

    • If the logistic partner can arrange and create Shipments, then the OMS doesn't need to bother about it; he will just place the items in the shipping order and is up for the logistic partner to create the individual shipments (e.g. ShipmentRefOrValue)
    • Suppose such capability is not present in the logistic partner. In that case, someone has to do it and then it can be the OMS or some other system in the enterprise landscape. Nevertheless, eventually, it can result in a ShippingOrder being placed where the items have already been organized in Shipment(s). Going back to my original example above with 3 items, if the OMS(or any other system on the fullfilment journey) has the capability, it can place directly 1 ShippingOrder -> with 3 ShippingOrderItem (pointing to the same Shippment)-> with 1 Shippment -> with 3 ShipmentItems (where each Shipment item has a unique SKU via Shipment->ShipmentItem->SKU and the corresponding references to the ProductOffering and to the ProductRefOrValue)


    On the 3rd point:
    I must admit I'm a little confused about your question here. If we are in the scenario where each ShippingOrderItem has a corresponding Shipment then each Shipment update can result in a ShippingOrderItem update. If multiple ShippingOrderItems point to the same Shipment (e.g., various devices in the same parcel) then once the Shipment is delivered all the ShippingOrderItems statuses will be updated.

    On your last point: "As I mentioned in base query, I am looking a guidance on implementation approach to keep this API product/customer facing service/resource agnostic. If consumer applications know least orderable info for shipping i.e., SKU/BOM ID, is using ShipmentItem data object for ShippingOrder creation right approach? Or Does it violate any standard guideline principle?"

    As mentioned above, the API follows the same patterns as in all other TMF APIs (especially the product definitions, ordering, etc).
    And in my view, if you already know the SKU item and you have all the indications on how the shipments should be created you can pass the information directly in the ShipmentRefOrValue->ShipmentItem; In my view it doesn't violate any principle;

    Thank you,
    Florin



    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 9.  RE: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation

    TM Forum Member
    Posted Nov 09, 2022 11:43
    thanks @Florin Tene, this helps to determine implementation approach​

    ------------------------------
    Pawan Makode
    [Amdocs Development Centre India Ltd]
    ------------------------------