Power tips: setting auto-delegate for other users using Powershell and the API

FileHold workflow is one of the most important features for adding efficiency and control to your processes. Ad hoc and predetermined assignment of tasks for users to perform on documents is a powerful mechanism to streamline your work with documents. When users go on leave they can tell workflow to automatically delegate their tasks to a colleague. The mechanism works great unless they forget to turn it on or their colleague is not available for some reason.

Fair warning, code to follow. You need to know a bit of Powershell to follow along and you can learn the FileHold API as you go via the FileHoldApi.psm1 wrapper we have prepared. You can plan a session with our professional services team to walk you through running this if you feel you would like a bit more help.

The good news is that the FileHold API provides a method needed for an administrator to update this setting for the user on leave. All they need is to provide the details of the user on leave and the user to delegate to, to the workflow notification settings feature.

UserPreferences.SetUserWorkflowNotificationSettings

This method takes two parameters: the GUID for the user on leave and a notification settings object. It must be run in the context of a user with the system administration role. Since we do not want to mess up most of the user’s settings, we will need to start with their current values and, as you probably guessed, the user preferences web service has a method for that as well.

UserPreferences.GetUserWorkflowNotificationSettings

Given the Powershell FileHold API helper I have presented in prior blogs, the code is fairly simple assuming you have logged in with Start-FileHoldSession.

$settings = (UserPreferences).GetUserWorkflowNotificationSettings( $userOnLeaveGuid )
$settings.DelegateToUser = $userSufferingBackHome
(UserPreferences).SetUserWorkflowNotificationSettings( $userOnLeaveGuid, $settings )

You can remove the automatic delegation by passing a null.

$settings.DelegateToUser = [System.Guid]::Empty

Now, you might be asking where to I get that GUID thing for the user. Well, a bit more work is required. Every user in FileHold has a GUID that identifies them. For an active directory domain user, this is their domain GUID. Local FileHold users have one defined on-the-fly when they are created. It turns out there is a simple API call for those as well. You just need to choose one of the search parameters.

$userObjects = (UserGroupManager).GetUserObjects( $startsWithName, $exactName, $exactEmail )

This method has some options that are useful, but not relevant for auto-delegation so we can take this opportunity to create a general-purpose cmdlet for getting user objects.

Get-FileHoldUserObjects [-SearchType <StartsWithName, ExactName, ExactEmail>]

It should have all the normal options for creating a session if needed, but the key is to choose the searching method then feeding search values from the pipeline.

‘russ beinder’, ‘jon franks’|Get-FileHoldUserObjects -SearchType ExactName -ReuseSession

For delegating users we should add a bit of error checking just in case our search returns more than one user object and feed the pipeline variable directly, but the code might now look something like this.

# Sign into FileHold up here
$FromUser = ‘russ beinder’ # Person on vacation
$ToUser = ‘jon franks’ # Person filling in
$fromUserObjects = Get-FileHoldUserObjects -ReuseSession -PreserveSession -ValueList $FromUser
$toUserObjects = Get-FileHoldUserObjects -ReuseSession -PreserveSession -ValueList $ToUser
$userOnLeaveGuid = $fromUserObjects[0].ID
$userSufferingBackHome = $toUserObjects[0].ID
$settings = (UserPreferences).GetUserWorkflowNotificationSettings( $userOnLeaveGuid )
$settings.DelegateToUser = $userSufferingBackHome
(UserPreferences).SetUserWorkflowNotificationSettings( $userOnLeaveGuid, $settings )
# Log out of FileHold here to make the current session available immediately

For your pleasure, we have wrapped the lines of code above with some error checking into Set-FileHoldAutoDelegateUsers.ps1. As a bonus we created Get-FileHoldAutoDelegateUsers.ps1 which will allow you to see the results of your handy work and Get-FileHoldUserObjects.ps1. Guess what that does. All the bits wrap up into a module called FileHoldCommand.psm1 which you can simply import into your environment. The whole process might appear as follows from the Powershell command line.

Image

Note that I have directly imported FileHoldApi.psm1 to make it possible for me to perform these many calls to FileHold with a single login session. The Start-FileHoldSession sets the stage.

The code for FileHoldCommand, FileHoldApi and associated files are attached at the end of the blog if you just want to go ahead and run these, but please take a dive into the source to see how you could leverage the FileHold API for your own specific purpose. The code expects you to drop it all into the same folder.

Set-auto-delegate.zip

This article and associated code is provided as-is for information only. It is assumed readers applying this information will have appropriate skill sets to interpret it correctly and, where possible, experiment on development or test servers. The FileHold professional services team can be contacted at [email protected] if their services are required.