Inquiries on Sonata APIs

[jesmanlangit]

Hello everyone - our team is developing Sonata APIs and our engineers are stuck and need help to get answers on the questions below. Therefore, am posting the inquiries here hoping the community would help answering them. TIA.

1. Both Interlude and Sonata have an identical error schema (Error422), but with different values, specifying this schema in the API can cause issues.
2. POST /cancelproductOrder
   In the MEF document example response for buyer and seller they have included the note parameter field. As per yaml file we do not have note parameter field in the response of buyer and seller. Is the note field necessary to be included in the response?
3. As per the documentation https://lso.mef.net/api-catalog/product-ordering-management-5 there is a 'Use Cases' section that includes a 'Initiate Charge' row but there is no corresponding Api ,so right now we are utilizing the 'productOrder' to initiate charges.Can you please confirm on this?
4. What is the clear definition of installationInterval field key?
5. Currently, in the "/listener/productOrderItemExpectedCompletionDateSet" API, the expected completion date is supplied by the seller. I'm verifying that a valid value (i.e., not equal to "none") is provided. If a valid value is present, the API will respond with a status code of 204 for the notification. Is my interpretation correct, and could you please provide guidance if needed?
6. There is no information about "eventId" in the MEF documentation related to notification APIs. As a result, we are considering "eventId" as hub id which is generated by seller when we subscribe for notification by using /hub api . Could you please verify if my approach is correct?
7. How can we determine whether notification APIs are subscribed for Notification?.There is hub ApI for registering notifications but how we can relate to notification Api.Could you please guide on this .
8. There is no proper information about chargeCreateEvent API in the MEF document. On what basis should notification be triggered?
   We are considering when the charge is created. I am sending a notification. Could you please verify if my approach is correct?
9. Their is no proper information about productSpecificProductOrderItemMilestoneEvent API in the MEF document .On what basis should notification be triggered,
   In the product order (post) response we have a milestone name, we are relating the milestone name,I am sending Notificaton on this creteria.Could you please verify if my approach is correct?
10. As per the MEF W142, [CR19]<[O10] The Seller must send a categoryAttributeValueChangeEvent whenever any of the following Product Category attributes are updated.
    There are three attributes (parentCategory, subCategory, and productOffering). parentCategory, subCategory, and productOffering are all arrays of objects. A notification (status code 204) must be sent if any changes occur in these attributes. As a result, the document does not provide any specific condition on how to determine if the values have changed.
    Could you please suggest me how to address this situation effectively?
11. As per the MEF W142, [CR21]<[O11] The Seller must send a productOfferingAttributeValueChangeEvent whenever any of the following Product Offering attributes are updated.
    There are 11 attributes (channel, agreement, marketSegment, region, category, statusTransitions, attachment, relatedContactInformation, productOfferingTerm, note). channel, agreement, marketSegment, region, category, statusTransitions, attachment, relatedContactInformation, productOfferingTerm and note are all arrays of objects. A notification (status code 204) must be sent if any changes occur in these attributes. As a result, the document does not provide any specific condition on how to determine if the values have changed.
    Could you please suggest me how to address this situation effectively?

[MichalLaczynskiAmartus]

Hi @jesmanlangit .

Thank you for the deep feedback. I assume based on the link in question 2 that you are implementing the Dolly release and will refer to that one in my answers.

1. There should be no discrepancies between Sonata/Cantata per the given API. There might have been a discrepancy between different APIs due to their lifecycle and the dictionary of errors was enhanced at some point. This might be a problem when you expose all your APIs via one OAS spec. But even if that is the case - the discrepancy is only the addition of the enum value so it is backward compatible. Any right implementation will not be harmed. Anyway - can please pinpoint directly the discrepancy you have noticed? I will add it to a fix list.
2. The example is not correct here. "note" was removed from CancelProductOrder in the Celine release and unfortunately it was not corrected in the example.
3. The initiate charge use case is started with the use of the Buyer side API by sending the Buyer the chargeCreateEvent. https://lso.mef.net/api-catalog/product-ordering-management/buyer-side-5. The use case name will be moved to be listed on the Buyer Side API spec to avoid confusion.
4. Per MEF 79: "The estimated minimum interval that the Seller requires in their standard process to complete the delivery of a Product from the time the or-der is placed, and any precedents have been completed."
5. Yes. A response to notification is just a 204 confirmation without any body.
6. "eventId", as defined in the description, is simply an ID of the event. This is presented also in the examples. So using hubID at this place is wrong because all events will have the same ID.
7. I do not understand the question. Buyer registers to notifications using hub/POST. The seller knows who is registered for which notification and what address to send the notifications to.
8. The charge process is defined in details in chapter 6.11 of MEF 123. The Charge Create event is sent upon Charge creation.
9. As per the documentation: "A request initiated by the Seller to notify the Buyer on Product Specific Product Order Item Milestone reached event." Of course, the milestone name must be the one that was reach, per the event name.
   10, 11. The condition is the occurrence of any change of any of these attributes. A change in the list attribute is when the response you provide will differ from the one that would have been provided prior to the change.

[jesmanlangit]

Hi @MichalLaczynskiAmartus - thank you so much for the answers, huge help! However, we're referring to the Fergie release. I hope these answers are still accurate/applicable.
Our engineering team is currently reviewing them. We'll probably throw more questions along the way. Thanks again.

[jesmanlangit]

Hi @MichalLaczynskiAmartus - is there any news on the finalized W151 APIs?

[MichalLaczynskiAmartus]

Hi. W 151 is Service attributes definition, not an API. Once finished in DSC the LSO will prepare a schema for it to be used across the LSO APIs. For now it is undergoing a CfC so at least one quarter until it will be finalized.
The project page is here: https://wiki.mef.net/pages/viewpage.action?pageId=207619054

[jesmanlangit]

Thanks for the @MichalLaczynskiAmartus.

Got a handful of queries again if you could help us:

1. REgarding all the notification APIs, since notification are used to asynchronously inform the buyer do we need to handle any validation for eventTime or just we can set it to current System time?

2. As per the MEF W142, [CR19]<[O10] The Seller must send a categoryAttributeValueChangeEvent whenever any of the following Product Category attributes are updated.There are three attributes (parentCategory, subCategory, and productOffering). parentCategory, subCategory, and productOffering are all arrays of objects. A notification (status code 204) must be sent if any changes occur in these attributes. As a result, the document does not provide any specific condition on how to determine if the values have changed.
   Could you please suggest me how to address this situation effectively?

3. As per the MEF W142, [CR21]<[O11] The Seller must send a productOfferingAttributeValueChangeEvent whenever any of the following Product Offering attributes are updated. There are 11 attributes (channel, agreement, marketSegment, region, category, statusTransitions, attachment, relatedContactInformation, productOfferingTerm, note). channel, agreement, marketSegment, region, category, statusTransitions, attachment, relatedContactInformation, productOfferingTerm and note are all arrays of objects. A notification (status code 204) must be sent if any changes occur in these attributes. As a result, the document does not provide any specific condition on how to determine if the values have changed. Could you please suggest me how to address this situation effectively?

Thanks in advanced @MichalLaczynskiAmartus .

[MichalLaczynskiAmartus]

1, No validation is needed, systemTime is what is expected to be set.
2,3 send a notification whenever any of mentioned attributes changes in your system.

[jesmanlangit]

Thank you @MichalLaczynskiAmartus !

[jesmanlangit]

Hi @MichalLaczynskiAmartus !

Happy new year!

We found some discrepancies in the MEF and the yaml document (Fergie version). Could you clarify them?

1. We couldn't find the fields parameters in the product - inventory API documentation despite its existence in the YAML file. Would you know whether which reference doc is acurrate?
2. In MEF 115 doc, the specified endpoint is "/declineQuote," whereas in the YAML file - quoteManagement.api, the endpoint is listed as /rejectQuote. Can you confirm which information is correct?
3. In the GET /trackingRecord and GET /trackingRecord/{id} under MEF W143. Tracking Records are used to track actions performed on entities like Performance Monitoring Profile, Performance Monitoring Job, and Performance Monitoring Report. However, for the 'GET /trackingRecord' API, there is no corresponding POST API, and no example response is provided. Some attributes like 'relatedObjectId', 'request', 'user', and 'system' are not defined in the documentation. In addition, the responses of Performance Job, Profile, or Report do not carry the 'relatedObjectId' attribute. This causes problems in associating the report from the create performance monitoring profile because of the absence of the id. Is this the expected framework or are we supposed to expect to use an id for these APIs?