Open APIs

Expand all | Collapse all

References to external resources

  • 1.  References to external resources

    TM Forum Member
    Posted Mar 09, 2021 14:33
    I'm hoping for some clarification on how best to store external references.

    If we take a scenario where there are multiple levels of order orchestration where 622 Product Order creates 641 Service Order which creates 652 Resource Order.
    Which pattern should be used in each layer, to store a reference to the order immediately downstream? (ie. 622 stores a reference to the 641 order. SOM stores a reference to the 652 order)
    622 Product Order doesn't have anything and I've found maybe three possible answers.

    1) Use the External Reference pattern from 641 as described in this thread - Open APIs
    Q: The externalReference doesn't have an id so unclear how this is to be used without an extension.

    2) Use EntityRef pattern from Part 2 of Design Guidelines
    Would require 622 adding a ServiceOrderRef to include the id, href of the 641 resource.

    3) Use the new ExternalIdentifiers pattern as described in this thread - Open APIs

    Could someone elaborate on the differences between these approaches and clarify which would be the best fit in the above scenario?

    Many thanks,
    Lynn

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------


  • 2.  RE: References to external resources

    TM Forum Member
    Posted Mar 10, 2021 00:48
    Hi Lynn
    I was responsible for introducing the new ExternalIdentifier data type into the Open API schema, so clearly this is my preferred approach.
    With that, it seems that it will take time to get it into the core API design since it is a compatibility break.
    I've opened a project JIRA issue (link is accessible only by project members) to have this documented in the design guidelines.
    Hope it helps

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: References to external resources

    TM Forum Member
    Posted Mar 10, 2021 05:52
    I think the requirement is wider than just external identifiers in order APIs.
    A particular Product Order may result in multiple service orders or Service Activation and Configuration (TMF 640) calls. There may be other API calls to create billing accounts etc may be needed.
    One option could be to populate a common identifier in all the API calls. This will allow stitching together of all the transactions resulting from a single customer request.
    So achieve this, we will need some id field that is available to populate in all Open APIs.



    ------------------------------
    Milind Bhagwat
    BT Group plc
    ------------------------------



  • 4.  RE: References to external resources

    TM Forum Member
    Posted Mar 10, 2021 11:52
    Agreed.  I see two similar use cases.

    1) correlation - a field that can be used to link entities across systems to indicate they are related in some way. (ie. all come from the same originating customer request)
    Originally when looking at 622 I thought externalId was a good fit for this correlation id.

    2)  reference -  POST calls on an edge system return the id of the external resource which may need to be tracked for PATCH or GET operations later.

    In my mind, the new array of ExternalIdentifiers is a perfect fit for #2. And my question is should that also be the solution for #1? Or is a first class correlation field a better option.


    @Jonathan Goldberg - is there any recommendation on where to store an id for correlation?

    thanks again
    Lynn​​​​

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------



  • 5.  RE: References to external resources

    TM Forum Member
    Posted Mar 11, 2021 02:36
    Hi @Lynn Dueck, @Milind Bhagwat
    A great discussion.

    We should distinguish between Lynn's two use cases, I think there is general agreement that for 2) we should use the external reference, and this was approved in principle in our Open API governance call ​​yesterday.

    Regarding 1), I think it would not be correct to push such an ID into the API model. A correlation or transaction ID is generally used to follow a sequence of API call flows (and/or event-initiated flows), and it is possible that HTTP headers and event headers would be a better place for this. Once the transaction is complete (successfully) I don't think anyone cares about the ID. Interesting to see what the community has to say about this.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 6.  RE: References to external resources

    TM Forum Member
    Posted Mar 12, 2021 10:01
    Hi,

    To track and correlate all functional requests/orders within our company (mainly SOAP), we use a Context object that contains among other things a correlationId.
    When we started integrating TMF APIs (REST), we injected this context as a Header in all calls to TMF modules. To support that, we developed for each API a client access layer that exposes the same methods as the API itself with the addition of other parameters (among which this context). The access layer takes care of serializing these parameters into JSON strings and adding these as HTTP headers.
    On the server side, we developed a small framework that takes cares of the symmetric operations to deserialize these HTTP headers into the corresponding Objects while still implementing the original TMF APIs.

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