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
------------------------------
Original Message:
Sent: Oct 28, 2022 03:08
From: Pawan Makode
Subject: TMF700: Product vs Shipment Item vs Product Catalog definition for ShippingOrder creation
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]
------------------------------