Upload and download of staff images

[BillP]

I'm looking to update the profile images of users from jpg files (not Active Directory) and I've found that there's an API activity::profileImageSet that lets me set an image (and a matching API activity::profileImageGet to retrieve the image).

1), are these the correct APIs to be using, or is there an API under admin:: that I should be using?

2), both of these require an objectRef, but the documentation doesn't say anything beyond:

Name    Type    Attributes    Description
objectRef    xs:anyURI    required once    The URN defining the social object who's profile image is to be looked up.

what would the URN for a user look like?

3), when downloading an existing image, an imageReference is specified, which is presumably relative to the WebDav root, or some subfolder thereof.  Can you confirm how to get from this to something that can be downloaded via WebDav

4), when uploading a new image via activity::profileImageSet I can see that I can specify an external URL, but I'd prefer to upload the JPG files via WebDav, as it keeps everything inside Hornbill and doesn't require me to post employee portraits to publicly-visible URLs.  Where should I post such images?

Thank you.

Bill

[BillP]

I found the URN format for a user in https://github.com/hornbill/goLDAPUserImport/blob/master/image.go

	hIF.SetParam("objectRef", "urn:sys:user:"+user.Account.UserID)

However, the rest of the process remains opaque.  Anybody?

[BillP]

@Steve G apologies for tagging you on this, but I've had no response on this in over 2 weeks.  Do I need to clarify the question?  Are my answers out there in the documentation and I just need to look harder?  

[Steve G]

Hi @BillP,

There's a good example of how to manage this requirement within the LDAP Import tool, in the userImageUpdate function from the image.go file you have linked above. The process is basically:

• HTTP PUT the file into the session folder in dav, with the link (replacing yourinstanceid and thefilename as appropriate ):  https://mdh-p01-api.hornbill.com/yourinstanceid/dav/session/thefilename.jpg
• Use  activity::profileImageSet to apply the profile image, where sourceImage would be /session/thefilename.jpg
• HTTP DELETE the file from your session folder in dav, with the link from the PUT. This is to ensure your session folder doesn't end up being full of unnecessary files.

Note, the HTTP PUT and HTTP DELETE need authenticating, so you'll need to provide the API Key for the user you are using in the Authorization header, in the same manner as you would for making XMLMC API calls into Hornbill.

With regards to the profileImageGet output, you can get these images via https://mdh-p01-api.hornbill.com/yourinstanceid/dav/_static/img/thevalueofimageReference_theimageresolution.jpg

So for example, if you had a user profile with an image reference of 50/0000002698, and you wanted the image with a resolution of 512x512, then your url would be:

https://mdh-p01-api.hornbill.com/yourinstanceid/dav/_static/img/50/0000002698_512x512.jpg

As always, you will need a valid session, or API key, to get at those images. Supported resolutions are:

• 16x16
• 24x24
• 32x32
• 54x54
• 64x64
• 128x128
• 200x200
• 220x264
• 256x256
• 512x512

Note, you don't need to update the image in these resolutions, the userProfileSet API takes care of the resize/cropping for you.

Hope this helps,

Steve

 

[BillP]

Hi @Steve G

Thank you - that worked perfectly.  For the benefit of the community, here is the PowerShell that I used:

#
# import external modules (originally installed from PSGallery)
#
Import-Module HornbillAPI
Import-Module PSFramework

#region Utility Functions

function Create-TempFolder
{
   $tmpDir = [System.IO.Path]::GetTempPath()
   $tmpFolder = [System.IO.Path]::GetRandomFileName()
   $tmpDir = Join-Path -Path $tmpDir -ChildPath $tmpFolder
  
   [System.IO.Directory]::CreateDirectory($tmpDir) | Out-Null

   $tmpDir
}

function Get-ImageFromURL ($SourceURL,$TargetPath,$HornbillKey) {
    Write-Host $SourceURL
    $headers = @{}
    if ($HornbillKey -ne $null) {
        $headers["Authorization"] = "ESP-APIKEY $HornbillKey"
    }
    try {
        $result = Invoke-WebRequest -Uri $SourceURL -Method GET -OutFile $TargetPath -Headers $headers
    }
    Catch {
        Write-Error $_.Exception.Message
        Write-PSFMessage -Level Debug -Tag "ERROR" -Message "Downloaded report $outputLocation failed: $($_.Exception.Message)"
    }
}

function Upload-ImageToSession ($LocalImagePath,$DestinationURL,$HornbillKey) {
    Write-Host $DestinationURL
    $headers = @{}
    if ($HornbillKey -ne $null) {
        $headers["Authorization"] = "ESP-APIKEY $HornbillKey"
    }
    try {
        $result = Invoke-WebRequest -Uri $DestinationURL -Method PUT -InFile $LocalImagePath -Headers $headers
    }
    Catch {
        Write-Error $_.Exception.Message
        Write-PSFMessage -Level Debug -Tag "ERROR" -Message "Downloaded report $outputLocation failed: $($_.Exception.Message)"
    }
}

#endregion

###################################################################
# Source of random faces
# see https://www.theverge.com/tldr/2019/2/15/18226005/ai-generated-fake-people-portraits-thispersondoesnotexist-stylegan
$faceURL = "https://thispersondoesnotexist.com/image"    # unique every time
$maleFace = "https://images.generated.photos/3m_U6OpnJvpM8HUrtmpIuH113nnU6QNDMnNGkVq9VkM/rs:fit:512:512/wm:0.95:sowe:18:18:0.33/Z3M6Ly9nZW5lcmF0/ZWQtcGhvdG9zL3Yz/XzA5NDI4MDQuanBn.jpg"

$UserName = "zebz"           # test user 1
$UserName = "aarona"         # test user 2

#region Fetch a random image for testing

if ($TempFolder -eq $null) {
    $TempFolder = Create-TempFolder
}

$UserImageJPG = "$UserName.jpg"

$imagePath = Join-Path $TempFolder $UserImageJPG

if (-not (Test-Path -LiteralPath $imagePath)) {
    Get-ImageFromURL -SourceURL $faceURL -TargetPath $imagePath # -HornbillKey $HornbillAPIKey
}

#endregion

$baseEndpoint = "https://eurapi.hornbill.com/myorganisationhere"
$davendpoint = "$baseEndpoint/dav"

#
# we have a source image - upload it to the dav/session area

$SourceImage = "/session/$UserImageJPG"

$HornbillTempImageURL = $davendpoint + $SourceImage

Upload-ImageToSession -LocalImagePath $imagePath -DestinationURL $HornbillTempImageURL -HornbillKey $HornbillAPIKey

#
# image is uploaded - now set it as the profile image.
# note the use of the deleteSourceFile parameter to delete the image - this stops filling the dav/session area with junk
$UserReference = "urn:sys:user:$UserName"
Add-HB-Param "objectRef" $UserReference 
Add-HB-Param "sourceImage" $SourceImage 
Add-HB-Param "deleteSourceFile" $true        # omit to keep the source image - why would you want to do this, though?
$xmlmcOutput = Invoke-HB-XMLMC "activity" "profileImageSet"
if ($xmlmcOutput.Status -ne "ok") {
    Write-PSFMessage -Level Debug -Tag "ERROR" -Message "failed to set user profile image : $($xmlmcOutput.Error)"
}

#
# now fetch it back at 256x256 resolution (original was at 1024x1024)

#
# step 1 - get the image reference
Add-HB-Param "objectRef" $UserReference 
$xmlmcOutput = Invoke-HB-XMLMC "activity" "profileImageGet"
if ($xmlmcOutput.Status -ne "ok") {
    Write-PSFMessage -Level Debug -Tag "ERROR" -Message "failed to get user profile image : $($xmlmcOutput.Error)"
}
$imageReference = $xmlmcOutput.Params.imageReference

#
# step 2 - build the url and fetch the file
$res = "_256x256.jpg"
$HornbillFetchImageURL = $davendpoint + "/_static/img/$imageReference" + $res
$downloadPath = Join-Path $TempFolder "$UserName$res"
Get-ImageFromURL -SourceURL $HornbillFetchImageURL -TargetPath $downloadPath -HornbillKey $HornbillAPIKey

Hope that's of use.

Thanks again

Bill