Support

Velocity Reporting: changing Jama hyperlinks into references to other places in the document

  • 1.  Velocity Reporting: changing Jama hyperlinks into references to other places in the document

    Posted 11-27-2019 05:47

    I created a small piece of velocity code that can fix hyperlinks to your jama items (in the jama website) and turn them into usable references to items inside the same document.
    The problem that we found was this:
    Let's say you have item A in Jama and you created a link to item B. Jama exports this link as a hyperlink to your Jama website, like this: Introduction
    But sometimes when you export your document, you want those useless hyperlinks to turn into links to another place in the document. You want your word/pdf document to link to the place where item B is found. This allows those who view the document to jump between item A and B easily.

    You can use the following Velocity Macro in your velocity template to do that.
    Just made sure that instead of writing the names of items in the document, you will write:
    <a name="$doc.globalId">the title of the item</a>
    This creates an html anchor to item the referenced item.

    The macro itself creates the html reference. The data is saved as $textWithFixedHyperlinks. The macro only affects those useless links to your Jama website but will not affect other links to other websites.

    #### a macro that replaces useless hyperlinks created in Jama with funtional references to other places in the document.
    ## the hyperlink will be created to an anchor in the same document - <a name="$doc.globalId">.
    ## if that globalId isn't in this document, the hyperlink will be created for the item's name.
    ## to create an Anchor for an item: <a name="$doc.globalId">the title of the item</a>
    #macro( fixHyperlinks35 $input)
                  ## the script returns $textWithFixedHyperlinks.
                  #set( $textWithFixedHyperlinks = "" )
                  #set( $textWithFixedHyperlinks = $input )
                  ## looking for up to 100 hyperlinks. there are no while-loops in velocity.
                  #set( $stop = 50 )
                  #set( $range = [1..$stop] )
                  #set($one = 1)
                  ## a useless jama hyperlink begins with "<a href".
                  #set( $hyperlinkStart = $textWithFixedHyperlinks.indexOf("<a href") )
                  #foreach( $i in $range )
                                 ## if there's a real hyperlink in this iteration, then...
                                 #if( $hyperlinkStart != -1)
                                               ## finding the whole hyperlink.
                                               #set($one = 1)
                                               #set($six = 6)
                                               #set( $hyperlinkEnd = $textWithFixedHyperlinks.indexOf(">", $mathTool.toInteger($hyperlinkStart) ) )
                                               ## making sure we found the whole hyperlink.                                
                                               #if( $hyperlinkStart != -1 && $hyperlinkEnd != -1)
                                                              #set( $hyperlinkEndPlusOne = $mathTool.toInteger($hyperlinkEnd) + $one )
                                                              #set( $hyperlinkSubstring = $textWithFixedHyperlinks.substring( $hyperlinkStart , $hyperlinkEndPlusOne ))
                                                              ## if the hyperlink was found, we need to make sure it's a useless jama hyperlink. find "docId=" within the hyperlink.
                                                              #set( $hyperlinkItemIdPos = $hyperlinkSubstring.indexOf( "docId=" ) + 6 )
                                                              ## if found, then it's truly a useless jama hyperlink.
                                                              #if( $hyperlinkItemIdPos != -1)
                                                                            ## change the link from Jama, that looks like a url, to a reference to another place in the document with the right global Id.
                                                                            #set( $temp = '"')
                                                                            #set( $hyperlinkItemIdEndPos = $hyperlinkSubstring.indexOf( "$temp", $mathTool.toInteger($hyperlinkItemIdPos) ) )
                                                                            #set( $hyperlinkItemId = $hyperlinkSubstring.substring($hyperlinkItemIdPos, $hyperlinkItemIdEndPos) )
                                                                            #set($referencedDoc = $docDao.getDocument( $mathTool.toInteger($hyperlinkItemId) ) )
                                                                            #set($textWithFixedHyperlinks = $textWithFixedHyperlinks.replaceAll("href=.*;docId=$hyperlinkItemId", "href=#$referencedDoc.globalId") )
                                                              #end
                                               #end                                  
                                 #else
                                               #break
                                 #end
                                 #set($ten = 10)
                                 #set( $hyperlinkStart = $mathTool.toInteger($hyperlinkStart) + $ten )
                                 #set( $hyperlinkStart = $textWithFixedHyperlinks.indexOf("<a href", $mathTool.toInteger($hyperlinkStart) ) )
                  #end
    #end
    You can also add the following code to report if there are hyperlinks to jama items that are not referencing items found in your exported document. You should add it before the content of the documents start so people can fix those hyperlinks.
    ## In order to find references (hyperlinks) that link to items not in this document,
    ## getting a list of all globalIds in this whole-document.
    #set($globalIdList = [])
    #foreach( $vDoc in $documentList )
                  #if( $globalIdList.add($vDoc.document.globalId ))#end
    #end
    ## iterating over all fields of all items. finding hyper;inks to item ids, then find the referenced item's global Id.
    ## if the global ID isn't in this whole-document, write an error message.
    #foreach( $vDoc in $documentList )
                  #set($docType = $vDoc.document.getDocumentType())
                  #set($docTypeId = $docType.getId())
                  #set ($docTypeFields = [])
                  #set ($docTypeFields = $documentTypeFieldDao.getDocumentTypeFieldListByType($docTypeId))
                  #foreach ($field in $docTypeFields)
                                 #set( $myFieldValue = "" )
                                 #set( $myFieldID = $field.documentField.getId())
                                 #set( $myDocTypeField = $documentTypeFieldDao.getDocumentTypeField($myFieldID, $docTypeId))
                                 #set( $dto = $documentTypeService.getDocumentFieldDtoFor($myDocTypeField.getId(), $project.getId()))
                                 #set( $myFieldValue = $velocityReportUtil.getValueForField($vDoc.document, $dto, $dateFormat))
                                 ##$dto.label : $myFieldValue<br>
                                 ## looking for up to 50 hyperlinks. there are no while-loops in velocity.
                                 #set( $stop = 50 )
                                 #set( $range = [1..$stop] )
                                 #set($one = 1)
                                 ## a useless jama hyperlink begins with "<a href".
                                 #set( $hyperlinkStart = $myFieldValue.indexOf("<a href") )
                                 #foreach( $i in $range )
                                               ## if there's a real hyperlink in this iteration, then...
                                               #if( $hyperlinkStart != -1)
                                                              ## finding the whole hyperlink.
                                                              #set($one = 1)
                                                              #set($six = 6)
                                                              #set( $hyperlinkEnd = $myFieldValue.indexOf(">", $mathTool.toInteger($hyperlinkStart) ) )
                                                              ## making sure we found the whole hyperlink.
                                                              #if( $hyperlinkStart != -1 && $hyperlinkEnd != -1)
                                                                            #set( $hyperlinkEndPlusOne = $mathTool.toInteger($hyperlinkEnd) + $one )
                                                                            #set( $hyperlinkSubstring = $myFieldValue.substring( $hyperlinkStart , $hyperlinkEndPlusOne ))
                                                                            ## if the hyperlink was found, we need to make sure it's a useless jama hyperlink. find "docId=" within the hyperlink.
                                                                            #set( $hyperlinkItemIdPos = $hyperlinkSubstring.indexOf( "docId=" ) + 6 )
                                                                            ## if found, then it's truly a useless jama hyperlink.
                                                                            #if( $hyperlinkItemIdPos != -1)
                                                                                          ## makes sure the jama hyperlinks references a real globalId from the current whole-document.
                                                                                          #set( $temp = '"')
                                                                                          #set( $hyperlinkItemIdEndPos = $hyperlinkSubstring.indexOf( "$temp", $mathTool.toInteger($hyperlinkItemIdPos) ) )
                                                                                          #set( $hyperlinkItemId = $hyperlinkSubstring.substring($hyperlinkItemIdPos, $hyperlinkItemIdEndPos) )
                                                                                          #set($referencedDoc = $docDao.getDocument( $mathTool.toInteger($hyperlinkItemId) ) )
                                                                                          #if( !$globalIdList.contains($referencedDoc.globalId) )
                                                                                                         <p>ERROR: The item $vDoc.document.name ($vDoc.document.globalId) contains a broken reference to $referencedDoc.id
                                                                                                        ($referencedDoc.name, $referencedDoc.globalId)
                                                                                                         in the field $dto.label<p>
                                                                                          #end
                                                                            #end
                                                              #end
                                               #else
                                                              #break
                                               #end
                                               #set($ten = 10)
                                               #set( $hyperlinkStart = $mathTool.toInteger($hyperlinkStart) + $ten )
                                               #set( $hyperlinkStart = $myFieldValue.indexOf("<a href", $mathTool.toInteger($hyperlinkStart) ) )
                                 #end
                  #end
    #end


    ------------------------------
    Roy Meirman
    Zoll Medical Israel
    ------------------------------