Support

Expand all | Collapse all

Velocity noob Q: What is $documentList object type?

  • 1.  Velocity noob Q: What is $documentList object type?

    Posted 12-01-2016 19:00

    Hi,

    The Jama help documentation (http://help.jamasoftware.com/index.html?report_parameters.htm) has a quick overview addressing the development of Velocity-based reports.  For "context sensitive" reports it indicates that the $documentList object will be provided and also provides a rough outline of the structure.  And it points to http://www.jamasoftware.com/api/latest/ where all Jama API classes are described.  However, it's not clear to me what class the $documentList object is instantiated from.  I'm not even sure which package to look at.  Help?

    Thanks,
    Mike

    ------------------------------
    A signature because apparently I have to have one...
    ------------------------------


  • 2.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-02-2016 17:14

    Hi Mike,

    Thank you for posting your question in our community. 

    documentList is an ArrayList of VelocityReportDTO object. I am afraid our API does not have that object, but we do have examples on how that can be used.  You can get to a Document object through it and use all the methods that Document object has. 

    See an example in our help guide that shows how it can be used. Here is another example of using documentList. I hope this is helpful. 

    ------------------------------
    Shabnam Jahromi Developer Support Engineer
    Jama Software



  • 3.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-02-2016 18:51
    Edited by Mike LastName 12-02-2016 18:52

    Thanks for your response, Shabnam.

    Unfortunately the example you link and the other content I have found is only of limited use.  What would really be helpful is a pointer to the definition of the VelocityReportDTO class so that my group can be more knowledgeable when creating our Velocity reports.  Or if that is not available, since the VelocityReportDTO seems to be made up of a collection of other objects, then a pointer to the full definition of all those objects.

    As an example, the Jama Objects help page notes that a single VelocityReportDTO object consists of the following objects:

    • document
    • documentTypeDTO
    • relationships
    • tags
    • documentFieldDTO
    • functions

    For the document object, the help page seems to indicate a limited list of fields are returned.  This does not match with the Document class definition so it's not clear if the help page is simply being intentionally brief or if the document object returned in the VelocityReportDTO object actually is of a different type than what is defined in the API documentation.

    Similarly, I could not find a definition for documentTypeDTO, relationships (obviously an array but not sure of what type; maybe it is a relationshipDAO object?), tags (also an array, but of what type; maybe a Tag object?), or documentFieldDTO objects.

    Finally, is it correct that the only two functions available through the VelocityReportDTO object are getDocument() and getValueForField()?

    What we're struggling with is that the $documentList seems like it returns a portion of what we need if the structure given in the help page is accurate, but other portions of the help file imply that it is not accurate. If we assume the structure in the help document is correct, then we need to retrieve more complete data using the getDocument() call (which isn't a big deal with a few thousand records but becomes unwieldy with several 10's of thousands of records).  On the other hand, if the VelocityReportDTO object is actually returning more complete data (more like the Document definition), then we are wasting time to retrieve the same data again record-by-record.

    As an example of the help file contradictions, in the link you provided to the help document, one example shows:

    #foreach($relate in $vDoc.relationships)
           ${relate.documentKey}
    #end

    Yet in the structure for relationships on the help page I linked above, it shows:

    relationships - All the directly related items to the document. Includes both upstream and downstream relationships. (Only available when parameter is configured)
     - traceId (Integer)
     - forward (boolean)
     - traceType (Lookup)
     - traceStatus (Lookup)
     - traceDescription (String)
     - suspect (boolean)
     - relationshipType (RelationshipsType)
     - documentId (Integer)
     - documentName (String)
     - documentGroup (String)
     - documentType (String)
     - documentStatus (Lookup)
     - documentRelease (Release)
     - assignedTo (String)
     - projectName (String)

    As you can see, no documentKey field is listed. 

    So it seems very possible to us that the $documentList array is really returning more data than what is listed in the help document.  It would be extremely beneficial to know the specific objects returned by the VelocityReportDTO object so that we can take maximum advantage in our Velocity reports.

    Thanks,
    Mike

    ------------------------------
    This is my signature; I hope you like it.



  • 4.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-05-2016 14:07

    Hi Mike,

    In talking with Shab, it's clear that this new set of questions is going to take a bit of time to dig into. I'm going to create a support ticket so we can properly track that time. (I'll end up copy-and-pasting the answer here in case anyone else is curious!) 

    ------------------------------
    Kristina King
    Jama Software



  • 5.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-05-2016 17:34

    Thank you Kristina!

    I'm surprised no one else has asked for this level of detail... leave it to us to be the ones that cause trouble... 8^P

    Mike

    ------------------------------
    Business is like a wheelbarrow - it stands still unless someone pushes it.



  • 6.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-21-2017 09:22
    Followup - it has been a year since the last post in this thread. Was there any response to Mike's questions? Can you please include the response here in the thread? thanks, Mike M.

    ------------------------------
    Mike Mattinson
    Leidos
    Orlando FL
    781-698-6491
    Mike
    ------------------------------



  • 7.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-22-2017 12:13
    Hi @Mike!

    Yeah, I didn't follow up and post the answer like I promised. I found the support ticket filed, and here's what it contained...

    About the Document object used in the helpguide:

    For the document object, the help page seems to indicate a limited list of fields are returned. This does not match with the Document class definition so it's not clear if the help page is simply being intentionally brief or if the document object returned in the VelocityReportDTO object actually is of a different type than what is defined in the API documentation.

    The help page is only showing an example and it's intentionally brief. The vDoc.document that is used in the help guide is returning an object of type Document that you can see in the API doc.

    Here are the objects that you can access through VelocityReportDTO

    ContourItem document;
    List<Document_Tag> tags;
    List<DocumentTraceDTO> relationships;
    DocumentTypeDTO documentTypeDto

    ContourItem and Document_Tag are available via AIP, but the other two are not. At this point, I can file a defect/problem statement for that to see whether we can improve our API. 
    I also have copied the variable that you can get access to via getters for DocumentTraceDTO as that seems to be what you are using. If the isForward flag true that means Jama will return the downstream item as you assumed.



    ------------------------------
    Kristina King
    Jama Software
    ------------------------------



  • 8.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-11-2018 19:24
    Hi Jama -
    Would it be possible to add a definition page for VelocityReportDTO to "http://velocity.jamasoftware.com/latest"? I see references to "com.jamasoftware.contour.api.plugin.VelocityReportDTO", but there's no corresponding page.

    Thanks,

    ------------------------------
    Theresa
    Fujifilm SonoSite
    WA United States
    ------------------------------



  • 9.  RE: Velocity noob Q: What is $documentList object type?

    Posted 12-13-2018 12:37
    Theresa:

    I wanted to communicate to you that I have put in an inquiry on this with our team. I will get back to this thread once I have more information for you but, I wanted you to know I was working on it.

    Best,

    ------------------------------
    Chloe Elliott
    Jama Software
    Portland OR
    ------------------------------