Automating task completion

[BillP]

Context: I'm looking at automating tasks around employee lifecycle management - new starters and leavers. We have service requests associated with these events, and those have associated tasks, such as creation of Active Directory accounts, or the setting of an account expiration date on an AD account. I'm trying to navigate from the entity to get a list of all the tasks associated with a given service request.

 

$SRRef = "SR00055137"

    Add-HB-Param -ParamName "requestId" -ParamValue $SRRef
    Add-HB-Param -ParamName "returnRelatedData" -ParamValue "true"
    Add-HB-Param -ParamName "returnActivityStreamAccessToken" -ParamValue "true"
    $xmlmcOutput = Invoke-HB-XMLMC "apps/com.hornbill.servicemanager/Requests" "getRequestRecord"
    if ($xmlmcOutput.Status -eq "fail") {
        Write-PSFMessage -Level Debug -Tag "ERROR" -Message "failed to update request timeline: $($xmlmcOutput.Error)"
    }
    $MainInfo = $xmlmcOutput.Params.primaryEntityData | ConvertFrom-Json
    $RelatedInfo = $xmlmcOutput.Params.relatedEntityData | ConvertFrom-Json

    $primaryEntityData = $xmlmcOutput.Params.primaryEntityData | ConvertFrom-Json
    $activityStreamId = $primaryEntityData.record.h_activity_stream_id
    $accessToken = $xmlmcOutput.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

    $activityStream | foreach {
        $activity = $_
        if ($activity.content -match "^Task '{""Set Active Directory Account to Expire"", ""([a-zA-Z0-9\:\.]+)""}' was added$") {
            $activity | Out-Null
            $taskUrn = $Matches[1]
            if ($taskUrn -match ".*(TSK[0-9]*)") {
                $taskId = $Matches[1]
                #
                # get the info for the task
                Add-HB-Param -ParamName "taskId" $taskId
                $requestOutput = Invoke-HB-XMLMC "task" "taskGetInfo"
                if ($requestOutput.Status -ne "ok") {
                    #
                    Write-Host "failed"
                }
                $taskInfo = $requestOutput.Params
                #
                # now we can get a list of all tasks
                $SRUrn = $taskInfo.objectRefUrn
                Add-HB-Param -ParamName "objectRefUrn" $SRUrn
                $requestOutput = Invoke-HB-XMLMC "task" "taskGetList"
                if ($requestOutput.Status -ne "ok") {
                    #
                    Write-Host "failed"
                }
            }
        }
    }

First Question - I was expecting to be able to get a list of tasks from apps/com.hornbill.servicemanager/Requests::getRequestRecord - but nothing obvious showed up in the responses. Instead I got there by parsing elements of the activity stream to find the notification that a task I was interested in had been added. From that I parsed the Task's Urn, and from that the TaskId.  Surely there's a simpler way?

From that TaskId I was able to invoke task::taskGetInfo which gave me info about the task. I was able to see the format of the Urn for the service request - urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137 .

Second Question - I was expecting hoping to be able to get a list of tasks using task::taskGetList specifying the Urn of the service request to limit the output to tasks belonging to that service request. The request succeeded, but returned an empty list. Can I use task::taskGetList to get a list of tasks belonging to a service request, and if so, what parameters do I need to supply.

[Steve Giller]

@BillP What are you using as the objectRefUrn?

Testing on my Instance with

<objectRefUrn>urn:sys:entity:com.hornbill.servicemanager:Requests:IN00000244</objectRefUrn>

I get the three Tasks assigned to IN00000244 returned from taskGetList.

[BillP]

@Steve Giller The value of objectRefUrn is:
urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137

immediately after executing the task::taskGetList my debug session shows:

[DBG]: PS C:\Projects\LeaverTermination>> $taskUrn
urn:sys:entity:com.hornbill.core:task:TSK20210819000012

[DBG]: PS C:\Projects\LeaverTermination>> $SRUrn
urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137

[DBG]: PS C:\Projects\LeaverTermination>> $requestOutput

Status Params Error
------ ------ -----
ok                 



[DBG]: PS C:\Projects\LeaverTermination>> $requestOutput.Params

[DBG]: PS C:\Projects\LeaverTermination>> $requestOutput.Params -eq $null
True

[DBG]: PS C:\Projects\LeaverTermination>> $taskId
TSK20210819000012

[DBG]: PS C:\Projects\LeaverTermination>> 

 

Edited August 20, 2021 by BillP
missed tagging responder

[Steve Giller]

That looks correct, possibly there are other criteria at play?

It'd need someone with a deeper understanding of the API than me to answer, I'm afraid.

[SamS]

Hi @BillP,

You might want to try the following instead ( https://api.hornbill.com/xmlmc/apps/com.hornbill.core/Task?op=getEntityTasks ):

<methodCall service="apps/com.hornbill.core/Task" method="getEntityTasks">
<params>
  <objectRefUrn>urn:sys:entity:com.hornbill.servicemanager:Requests:SR00######</objectRefUrn>
  <counters>true</counters>
  <taskStatus>1</taskStatus>
  <rowstart>0</rowstart>
  <limit>10</limit>
</params>
</methodCall>

(naturally, modify URL to your own instance)

[BillP]

Thank you @SamS, I can confirm that this other API works. I checked out what happened when specifying multiple taskStatus values:

 

$SRRef = "SR00055137"

    Add-HB-Param -ParamName "requestId" -ParamValue $SRRef
    Add-HB-Param -ParamName "returnRelatedData" -ParamValue "true"
    Add-HB-Param -ParamName "returnActivityStreamAccessToken" -ParamValue "true"
    $xmlmcOutput = Invoke-HB-XMLMC "apps/com.hornbill.servicemanager/Requests" "getRequestRecord"
    if ($xmlmcOutput.Status -eq "fail") {
        Write-PSFMessage -Level Debug -Tag "ERROR" -Message "failed to update request timeline: $($xmlmcOutput.Error)"
    }

    Add-HB-Param -ParamName "objectRefUrn" "urn:sys:entity:com.hornbill.servicemanager:Requests:$SRRef"
    Add-HB-Param -ParamName "counters" -ParamValue "true"
    Add-HB-Param -ParamName "taskStatus" -ParamValue 0
    Add-HB-Param -ParamName "taskStatus" -ParamValue 1
    Add-HB-Param -ParamName "taskStatus" -ParamValue 2
    Add-HB-Param -ParamName "taskStatus" -ParamValue 3
    Add-HB-Param -ParamName "taskStatus" -ParamValue 4
    Add-HB-Param -ParamName "taskStatus" -ParamValue 5
    Add-HB-Param -ParamName "taskStatus" -ParamValue 6
    Add-HB-Param -ParamName "taskStatus" -ParamValue 7
    Add-HB-Param -ParamName "rowstart" -ParamValue 0
    Add-HB-Param -ParamName "limit" -ParamValue 10
    $xmlmcOutput = Invoke-HB-XMLMC "apps/com.hornbill.core/Task" "getEntityTasks"
    if ($xmlmcOutput.Status -eq "fail") {
        Write-PSFMessage -Level Debug -Tag "ERROR" -Message "failed to update request timeline: $($xmlmcOutput.Error)"
    }
    $taskInfo = $xmlmcOutput.Params.tasks | ConvertFrom-Json

 

Outputting the contents of $taskinfo I see:
 

[DBG]: PS C:\Projects\LeaverTermination>> $taskInfo


0 : {}
1 : {@{taskid=TSK20210819000013; status=1; title=Link Employees Assets; owner=SYS_BPM_MANAGER; outcomes=Completed; createdon=2021-08-19 15:24:56; priority=5; details=Link the employees assets to the request - these are to be returned on their last working 
    day; assigned=urn:sys:role:Service Desk; reference=bpmTask; progress=0; extra={}; objectrefurn=urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137}, @{taskid=TSK20210819000014; status=1; title=Line Manager Confirmation; 
    owner=SYS_BPM_MANAGER; outcomes=Completed; createdon=2021-08-19 15:24:56; priority=5; details=Contact the employees line manager to understand whether any special requirements are needed once the employee has left the organisation. e.g. e-mail 
    forwards, out-of-office, access to Onedrive etc.; assigned=urn:sys:role:Service Desk; reference=bpmTask; progress=0; extra={}; objectrefurn=urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137}}
2 : {}
3 : {}
4 : {@{taskid=TSK20210819000012; status=4; title=Set Active Directory Account to Expire; owner=SYS_BPM_MANAGER; outcomes=Completed; outcome=Completed; createdon=2021-08-19 15:24:56; completedon=2021-08-20 16:53:19; priority=5; details=Set the employees 
    Active Directory account to expire on the date specified; assigned=urn:sys:role:Service Desk; reference=bpmTask; progress=100; extra={}; timespent=0; objectrefurn=urn:sys:entity:com.hornbill.servicemanager:Requests:SR00055137}}
5 : {}
6 : {}
7 : {}




[DBG]: PS C:\Projects\LeaverTermination>> 

which would appear to correspond to 2 tasks not started and 1 task completed. The task status values of 1 and 4 are a bit opaque - but this gets me going.

Next stop - setting specific tasks to completed by the API.

Thanks again for the assistance.

[simonadams]

Hi @BillP

Which iBridge integration is this using ? I would like to investigate doing this for our Starters and Leavers process.

 

Kind Regards

Si

[BillP]

Hi @simonadams

This is a standalone PowerShell application (i.e. a set of powershell scheduled jobs), which manages Starters and Leavers directly. It's driven by our HR system (iTrent), which supplies Starter and Leaver notifications via a mix of emails to Hornbill and to a notification mailbox, all of which are cross-checked against each other in the powershell to build up the set of actions in AD, Azure AD, Office 365, Hornbill and (eventually) LoB apps. It all hooks into pre-existing Hornbill workflows that were designed for manual operation.

It's also a work in progress.

I'm happy to share more details if it helps, but that may not be of interest to this forum.

Let me know.

Bill Powell