API to read back posts from the request timeline

[BillP]

I'm writing an integration between Hornbill and the Software Development team's agile project board, Target Process (TP).  The Software Devs want to see support tickets come in from Hornbill and appear on their TP sprint board as a story (service request) or a bug (incident), to appear alongside all the other engineering work they do.  As they work on the bug (say), certain events need to be pushed back to the Hornbill request, so that the Operations Team can see progress without having to be licensed for TP.  This is straightforward - I have got this to work in powershell using:
    Invoke-HB-XMLMC "apps/com.hornbill.servicemanager/Requests" "updateReqTimeline"

What I now need to do is to read back all posts on the timeline, using a "complementary" API, so I can add these as comments to the bug in TP (obviously filtering out those created by the integration).

I have searched the servicemanager API documentation, but there's a bit of terminology I'm missing, because I can't find a get or read operation to retrieve posts from the timeline.

Please, what is that API?

[Steve G]

Hi @BillP,

You can use the activityStreamQuery API to pull paginated lists of posts (and optionally comments) from a requests timeline, using an access token and activity stream ID returned by a call to the getRequestRecord API. The activity stream ID will be returned in the h_activity_stream_id column within the primaryEntityData output parameter of getRequestRecord.

Let me know if you need any more info.

Cheers,

Steve

[BillP]

Thanks @Steve G

That all works nicely.  For the benefit of others here's the working code in the context of the larger task.  For the sake of clarity, I've not yet put in most of the error handling...

#
# check all tickets reported as owned by sweng team
# create new stories where tickets don't already have stories / bugs
# sync back changes once the TP entity is being worked on
$DevTicketList | where {$_.Status -notin @("status.closed","status.cancelled")} | foreach {
    $DevTicket = $_
    #
    # get the latest info from the ticket - the report may be out-of-date
    Add-HB-Param -ParamName "requestId" -ParamValue $DevTicket.RequestID
    $requestOutput = Invoke-HB-XMLMC "apps/com.hornbill.servicemanager/Requests" "smGetReqDetails2"
    if ($requestOutput.Status -ne "ok") {
        #
        Write-Host "failed"
    }
    else {
        #
        # we have the latest details for the Hornbill ticket
        $requestDetails = $requestOutput.Params.requestDetails | ConvertFrom-Json
        #
        # also fetch timeline - see https://community.hornbill.com/topic/20790-api-to-read-back-posts-from-the-request-timeline/
        Add-HB-Param -ParamName "requestId" $requestDetails.h_pk_reference
        Add-HB-Param -ParamName "returnActivityStreamAccessToken" "true"
        $requestOutput = Invoke-HB-XMLMC "apps/com.hornbill.servicemanager/Requests" "getRequestRecord"
        if ($requestOutput.Status -ne "ok") {
            #
            Write-Host "failed"
        }
        $primaryEntityData = $requestOutput.Params.primaryEntityData | ConvertFrom-Json
        $activityStreamId = $primaryEntityData.record.h_activity_stream_id
        $accessToken = $requestOutput.Params.accessToken
        #
        # now pull back the activityStream
        Add-HB-Param -ParamName "activityStreamID" $activityStreamId
        Add-HB-Param -ParamName "accessToken" $accessToken
        $requestOutput = Invoke-HB-XMLMC "activity" "activityStreamQuery"
        if ($requestOutput.Status -ne "ok") {
            #
            Write-Host "failed"
        }
        $activityStream = [object[]]($requestOutput.Params.activity)   # force it to always be an array
                                                                       # even if 0 or 1 elements

at this point the variable $activityStream contains a list (array) of rich objects, each representing a single post or other activity from the timeline. 

Note: The [object[]] construct may not be familiar to novice PowerShell users, but is used to force a return value which may be $null, an empty array, a single element, or a list of multiple elements to always be an array, with the intuitive number of elements, so that it can be consistently treated by whatever code follows, which in this case will be a foreach {} construction.

Hope that's useful.

[Steve G]

Hi @BillP,

No worries. Although if you're using smGetReqDetails2, you don't actually need the additional call to getRequestRecord, as smGetReqDetails2 provides an activity stream accessToken in the output params, as well as the activity stream ID in the requestDetails output param  

Cheers,

Steve