Open APIs

  • 1.  TMF667 - Document Management Specification [Doubts]

    TM Forum Member
    Posted Aug 31, 2018 04:32
    Hi,

    I have some doubts regarding the Document Management Specification

    1 - In the document Introduction it is stated that "... The query capabilities provided by this service will serve links (location references) as well as retrieve
    documents as binary objects..."
      but the response to the following endpoints.
    Requests:
              Retrieve Document
                   GET /documentManagement/document/42
              List Document
                                      GET /documentManagement/document?type="invoice"&relatedParty.id=42
            Responses
           "attachment": [{"attachment": [{ "size": "123.0", "sizeUnit": "bytes", "mimeType": "application/pdf", "URL": "/ documentManagement / document               /document.pdf "}],

    In the response we have the attachment and this represents the information of the binary object and it's location, is their way to actually retrieve the binary object with listDocument or retrieveDocument REST calls  (as it seems described in the introduction), or this always returns the binary object information and location?

    2 - Using CreateMethod Rest API we need to send three mandatory fields size, sizeUnit, mimeType. The URL is only mandatory on the response, this means that we only send the document location URL on the Request only when we have a remote file, do you confirm this? But the thing is how do is supposed to work when we have a local binary object to upload?

    Any clarifying about the questions please contact me.

    Thanks in advance.

    Best Regards,






    ------------------------------
    Luís Prates
    Celfocus
    ------------------------------


  • 2.  RE: TMF667 - Document Management Specification [Doubts]

    TM Forum Member
    Posted Oct 09, 2018 05:55
    Hi Luis
    To my best understanding, the Document Management API does not currently support direct manipulation of the content.
    The Attachment subresource represents the content, but the assumption is that the actual content bytes are stored in some management system outside the scope of the API, and the Attachment refers to this (via url and mime type).
    The following enhancements could be made, if someone would be prepared to take the leadership of this API:
    • Making Attachment as a separately managed resource (since Document is a fairly "heavy" resource, and many use cases just need the management of a file to a resource, without the full lifecycle and other goodies that Document gives)
    • Allowing Attachment to refer directly to the document content, so that the API would accept (POST/PATCH) and return (GET) the actual byte stream of the content.


    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    ------------------------------



  • 3.  RE: TMF667 - Document Management Specification [Doubts]

    Posted Sep 20, 2021 03:14

    Hi Jonathan,

    Recently we have reached to implementation of TMF667 and I was reading the past threads. According to your last post, please let me know :

    • Is there any nominate/owner/contributor working on document management? 
    • Is there any further update to this document after version 17.0.1 dated November 2017?

    Reading TMF620 I've seen there is an attachment reference or value  relation to ProductOffering, but I did not find the definition of attachment itself as a separate resource in swagger definition of TMF667, In this way it forces to create a higher level document resource according to TMF667 or using it as value only.

    I was confused till I've reached to this last post in this thread. You wrote : "Making Attachment as a separately managed resource", I Would appreciate if you give some clues for better understanding.

    Thanks
    Ebrahim



    ------------------------------
    Ebrahim Mirzazadeh
    ParsPooyesh
    ------------------------------



  • 4.  RE: TMF667 - Document Management Specification [Doubts]

    TM Forum Member
    Posted Sep 21, 2021 05:37
    Hello Ebrahim,

    As you know, attachment entity is used in many APIs. If you are going to use the attachment entity directly with any resource (eg document resource) instead of as a reference, you do not need to create a separate resource for the attachments. But this will make it difficult to manage the attachment content. It cause performance problems. You may need to add same content management rules to all the resources that use attachment.

    Therefore, it would be better to create a separate attachmentResource and use attachmentRef on all your other resources, including the documentManagemet api. Using references will seriously improve API performance. You can also integrate an open source document management system behind the attachment resource. In this way by using DMS, you gonna provide more effective content storage.

    ------------------------------
    Mustafa Yusufoglu
    i2i Systems
    ------------------------------



  • 5.  RE: TMF667 - Document Management Specification [Doubts]

    Posted Sep 22, 2021 02:01
    Hello Mustafa,

    Yes, You are right about performance of references, I am in the same side. My question was raised to resolve a doubt.
    As when as attachment is used in other entities I guess we need to create separate REST APIs (CRUD) for it (as already told earlier by Jonathan) , but data model in TMF667 shows it is defined as value in document entity. Meanwhile the swagger file shows neither required APIs nor listeners are not defined for "attachment". This is why I focused on asking for further update or contributor, because I was in doubt that this section needs to be updated.

    About integrating a DMS, it was good suggestion, already seen in our project roadmap.

    Best regards



    ------------------------------
    Ebrahim Mirzazadeh
    ParsPooyesh
    ------------------------------



  • 6.  RE: TMF667 - Document Management Specification [Doubts]

    TM Forum Member
    Posted Sep 30, 2021 11:19
    Sorry for delay, I was on vacation.
    Currently I don't have any news about making Attachment a separately managed resource with its own API operations.
    I guess we'll have to wait until this bubbles up into a priority item in the Open API team.

    ------------------------------
    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.
    ------------------------------